@mark1russell7/netdiag 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 This package has the core model of netdiag. It has the typed facts at each layer of the stack, the contract of a probe and the scope rule. It also has the catalog of faults and the probability model.
 
-**State: ND-1 and the model of ND-4 of the [roadmap](../../docs/ROADMAP.md).** The native probes (ND-2) come next. Then the readers change their facts into evidence for the model.
+**State: ND-1, ND-2, ND-4, and the lab score and the loopback lab of ND-7 of the [roadmap](../../docs/ROADMAP.md).** The kernel lab and the bars of the gate come next.
 
 ## Facts
 
@@ -43,6 +43,95 @@ An active probe sends packets only to a peer that the user owns or names. The ru
 
 The scope also limits the number of ports of each host. The default limit is 8. Thus netdiag does no port scan.
 
+## IP addresses
+
+The entry `@mark1russell7/netdiag/address` has plain functions for IP addresses and networks. It uses only the module `node:net`.
+
+| Function | What it gives |
+| --- | --- |
+| `addressFamily(address)` | `ipv4`, `ipv6`, or `undefined` for a text that is not an address. |
+| `addressClass(address)` | The class of the address, from the special-purpose ranges of RFC 6890. |
+| `addressKind(address)` | `private` for an address that the internet does not route to, else `public`. |
+| `parseCidr(text)` | A CIDR range, or the problem of the text. |
+| `cidrSet(ranges)` | A set of ranges. Its `has(address)` tells if an address is in a range of the set. |
+
+- The classes are `unspecified`, `loopback`, `private`, `shared`, `link-local`, `unique-local`, `documentation`, `benchmarking`, `multicast`, `reserved` and `public`.
+- The table `ADDRESS_CLASSES` holds the ranges of the classes as data.
+- An IPv4 address in IPv6 form, for example `::ffff:192.0.2.1`, is its IPv4 address.
+- An address for documentation is `public`. Thus a lab can use `203.0.113.0/24` for hosts on the internet.
+
+```ts
+import { addressClass, cidrSet, parseCidr } from "@mark1russell7/netdiag/address";
+
+addressClass("100.64.0.1"); // "shared": the carrier-grade NAT range
+const lab = parseCidr("203.0.113.0/24");
+if (lab.tag === "ok") cidrSet([lab.value]).has("::ffff:203.0.113.7"); // true
+```
+
+## Native probes
+
+The native probes use only the `node:` modules. They need no outside tool.
+
+| Probe | Id | Facts |
+| --- | --- | --- |
+| `DNS_PROBE` | `dns.query` | `dns.answer`: the outcome, the addresses and the lowest TTL of one query for `A` or `AAAA` records. |
+| `tcpProbe()` | `tcp.connect` | `tcp.connect`: the outcome and the time of one connect. |
+| `tlsProbe()` | `tls.handshake` | `tcp.connect` and `tls.handshake`: the time of the handshake, the version, the cipher, ALPN and the certificate. |
+| `httpProbe()` | `http.request` | `tcp.connect`, `tls.handshake` for `https`, and `http.response`: the status, some fields of the head and the time to the first byte. |
+
+- A probe connects only to an IP address. The DNS probe gives the addresses of a name first. Thus the runner examines each address against the scope.
+- The peer of the DNS probe is the resolver, not the name.
+- A time limit or a stop of the signal closes the socket. The probe then gives the outcome `timeout`, or the runner gives `aborted`.
+- The TLS probe does not refuse a certificate that is not valid. It records the problem, for example `expired`, `name` or `untrusted`.
+- The trust tells the root of the chain. `public` is a root of Node.js. `private` is a different root, for example the root of a proxy that examines TLS.
+- The option `roots` adds roots that the user trusts, for example the root of a company. Their trust is `private`.
+- The option `publicRoots` adds roots with the trust `public`. A lab gives its own root here, so its servers stand for servers on the internet.
+- The HTTP probe follows no redirect. It reads the body up to 64 KiB.
+- For `https`, the HTTP probe sends its request only when the certificate passes its check. Thus an interceptor does not get the path.
+
+```ts
+import { realClock } from "@mark1russell7/algebra/clock";
+import { TCP_PROBE, createRunner, scopeOf } from "@mark1russell7/netdiag";
+
+const scope = scopeOf([{ kind: "range", cidr: "192.168.1.0/24", basis: "owned" }]);
+if (scope.tag === "err") throw new Error(scope.error.join(" "));
+
+const runner = createRunner({ scope: scope.value, clock: realClock });
+const outcome = await runner.run(TCP_PROBE, { address: "192.168.1.1", port: 443 });
+// The fact tcp.connect has the outcome connected, refused, timeout, unreachable, reset or error.
+```
+
+## Outside tools
+
+The entry `@mark1russell7/netdiag/tools` has optional adapters of outside tools. netdiag bundles no tool. The user installs each tool.
+
+| Probe | Id | Tool | Facts |
+| --- | --- | --- | --- |
+| `pingProbe(host)` | `icmp.ping` | `ping` | `icmp.echo`: the echo replies, their round-trip times, and the messages of an unreachable address. |
+| `tracerouteProbe(host)` | `path.traceroute` | `traceroute`, `tracert` on Windows | `path.trace`: the routers that answered each TTL, their round-trip times, and the messages of an unreachable address. |
+| `mtrProbe(host)` | `path.mtr` | `mtr` (Linux and macOS) | `path.report`: the loss and the round-trip times of each hop over many cycles. |
+
+- A host starts each tool. Its `run(command, args, options)` starts a program with a list of arguments and no shell.
+- The function `runCommand` of `@procedures/shell` is a host with no change. A test gives a fake host.
+- An adapter reads only English output. On Linux and macOS, it sets `LC_ALL=C`. On Windows, the language of the system sets the output.
+- On Linux, the adapter reads the `ping` of iputils. On macOS, it uses `ping6` for an IPv6 address.
+- On Linux, the trace adapter reads the Modern traceroute (the package `traceroute`). On macOS, it uses `traceroute6` for an IPv6 address.
+- The `mtr` adapter reads the JSON report of `mtr --json` (version 0.92 or later). The default of 20 cycles takes approximately 20 seconds.
+- Output that netdiag cannot read gives the outcome `error` with the reason. It does not give a reply that did not occur.
+- The table `TOOL_LICENSES` holds the license of each tool as data. A tool with a restrictive license has no adapter.
+
+```ts
+import { runCommand } from "@procedures/shell";
+import { pingProbe, type ToolHost } from "@mark1russell7/netdiag/tools";
+
+const host: ToolHost = {
+  platform: process.platform,
+  run: (command, args, options) => runCommand(command, { args: [...args], timeout: options.timeoutMs, signal: options.signal, env: options.env }),
+};
+// The runner comes from the example of the native probes.
+const outcome = await runner.run(pingProbe(host), { address: "192.168.1.1", count: 20 });
+```
+
 ## Diagnosis
 
 The entry `@mark1russell7/netdiag/diagnosis` has the probability model. It imports no `node:` module, so a browser can also use it.
@@ -73,6 +162,69 @@ const result = diagnose(STANDARD_CATALOG, [
 // result.causes[0].id is "filter.icmp": a filter blocks ICMP, and the host is up.
 ```
 
+## Readers
+
+`readEvidence(facts, options)` changes the facts of the native probes and of the adapters into evidence for the model. Each value that it gives is a value of a feature of `STANDARD_CATALOG`.
+
+| Feature | The source of the value |
+| --- | --- |
+| `dns.answer` | The outcome of each DNS query. One answer `ok` for a name and a resolver decides. `nodata` gives `ok`, because the name exists. |
+| `dns.address` | The addresses of a public name. One private address decides. A local name, for example `nas.local`, gives no value. |
+| `ip.family` | The TCP connects to the IPv4 and the IPv6 addresses of one name. |
+| `tcp.connect`, `tcp.time` | The outcome and the time of each TCP connect. A time of 900 ms or more tells that the SYN went again. |
+| `tls.handshake`, `tls.trust` | The outcome of the handshake and the root of the certificate chain. A chain with no root of the store gives `private`. |
+| `tls.ratio` | The time of the handshake divided by the time of the last TCP connect to the same address and port. |
+| `http.status`, `http.ttfb` | The class of the status, and the time to the first byte divided by the time of the TCP connect. |
+| `gateway.reply` | The echo requests to the address of the option `gateway`. An unreachable gateway gives `none`. |
+| `icmp.reply` | The echo requests to each other address: `reply`, `none` or `unreachable`. |
+| `path.loss` | The share of the echo requests with a reply, for 20 requests or more: `none`, `some` (up to 5 % loss) or `high`. A report of `mtr` that reached the address gives it from its last hop. |
+
+- The reader gives one evidence for each feature, subject and role. When a subject has more facts, the last fact decides.
+- A fact that gives no evidence goes in `skipped`, with the reason. For example, the catalog has no value for the TLS outcome `not-tls` yet.
+- A fact `path.trace` gives no evidence yet. The catalog has no feature for the hops of a path. The lab runs (ND-7) fit one.
+- The option `primary` tells which facts are about the target. The other facts are about a reference host.
+- The option `gateway` gives the IP address of the default gateway.
+
+```ts
+import { STANDARD_CATALOG, TCP_PROBE, diagnose, readEvidence } from "@mark1russell7/netdiag";
+
+// The runner comes from the example of the native probes.
+const outcome = await runner.run(TCP_PROBE, { address: "192.168.1.1", port: 443 });
+if (outcome.status === "done") {
+  const { evidence, skipped } = readEvidence(outcome.facts);
+  const result = diagnose(STANDARD_CATALOG, evidence);
+  // A connect with the outcome refused gives result.causes[0].id "port.closed".
+}
+```
+
+## The lab score
+
+A lab makes one fault on purpose. Then netdiag must name it. The entry `@mark1russell7/netdiag/diagnosis` has the score of these runs.
+
+| Function | What it gives |
+| --- | --- |
+| `labRecordOf(catalog, case, truth, diagnosis)` | The record of one run: the true hypothesis, the predicted cause, the rank of the truth and the probability of each cause. |
+| `scoreLab(catalog, records)` | The confusion table, the recall of each hypothesis with its Wilson interval, the accuracy and the mean Brier score. |
+| `labGate(score, bars)` | A verdict for each hypothesis with a bar: `pass`, `fail` or `no-read`. |
+
+- The recall of a hypothesis is the part of its runs where the diagnosis names it.
+- A hypothesis passes when the lower end of its recall interval is its bar or more.
+- A hypothesis with no runs gets `no-read`, and the gate does not pass.
+- A hypothesis with no bar goes in `unbarred`, for example a fault that no lab can make.
+
+```ts
+import { STANDARD_CATALOG, diagnose, labGate, labRecordOf, scoreLab } from "@mark1russell7/netdiag/diagnosis";
+
+const diagnosis = diagnose(STANDARD_CATALOG, [{ feature: "tcp.connect", value: "refused", primary: true }]);
+const record = labRecordOf(STANDARD_CATALOG, "port.closed/refused", "port.closed", diagnosis);
+if (record.tag === "err") throw new Error(record.error);
+
+const score = scoreLab(STANDARD_CATALOG, [record.value]);
+if (score.tag === "err") throw new Error(score.error.join(" "));
+const gate = labGate(score.value, { "port.closed": 0.1 });
+// gate.value.verdicts[0].status is "pass": the lower end of the recall of 1 run of 1 is 0.21.
+```
+
 ## Example
 
 ```ts

package/build/address.d.ts

@@ -0,0 +1,56 @@
+import { Result } from "@mark1russell7/optional";
+/** The family of an IP address. */
+export type AddressFamily = "ipv4" | "ipv6";
+/**
+ * The class of an IP address, from the special-purpose ranges of RFC 6890.
+ *
+ * - `unspecified`: `0.0.0.0/8` and `::`.
+ * - `loopback`: `127.0.0.0/8` and `::1`.
+ * - `private`: the ranges of RFC 1918.
+ * - `shared`: `100.64.0.0/10`, the carrier-grade NAT range of RFC 6598.
+ * - `link-local`: `169.254.0.0/16` and `fe80::/10`.
+ * - `unique-local`: `fc00::/7`, the private range of IPv6 (RFC 4193).
+ * - `documentation`: the ranges of RFC 5737 and RFC 3849 for examples.
+ * - `benchmarking`: `198.18.0.0/15` (RFC 2544).
+ * - `multicast`: `224.0.0.0/4` and `ff00::/8`.
+ * - `reserved`: `240.0.0.0/4`, with the broadcast address.
+ * - `public`: each other address.
+ */
+export type AddressClass = "unspecified" | "loopback" | "private" | "shared" | "link-local" | "unique-local" | "documentation" | "benchmarking" | "multicast" | "reserved" | "public";
+/** A CIDR range: an address of the network and the length of its prefix. */
+export interface Cidr {
+  readonly address: string;
+  readonly prefix: number;
+  readonly family: AddressFamily;
+}
+/** The special-purpose ranges, as data. An address that is in no range is `public`. */
+export declare const ADDRESS_CLASSES: readonly {
+  readonly cidr: string;
+  readonly class: Exclude<AddressClass, "public">;
+}[];
+/** This function gives the canonical form of an address: no spaces, no brackets, lower case, and IPv4 for a mapped IPv4 address. */
+export declare function canonicalAddress(address: string): string;
+/** This function gives the family of an IP address, or `undefined` for a text that is not an IP address. */
+export declare function addressFamily(address: string): AddressFamily | undefined;
+/** This function gives the CIDR range of a text, for example `192.0.2.0/24` or `2001:db8::/32`. An address alone is a range of one address. */
+export declare function parseCidr(text: string): Result<Cidr, string>;
+/** This function gives the text of a CIDR range. */
+export declare function formatCidr(cidr: Cidr): string;
+/** A set of CIDR ranges. */
+export interface CidrSet {
+  readonly ranges: readonly Cidr[];
+  /** This function tells if an address is in a range of the set. A text that is not an IP address is in no set. */
+  has(address: string): boolean;
+}
+/** This function gives the set of some CIDR ranges. */
+export declare function cidrSet(ranges: readonly Cidr[]): CidrSet;
+/** This function tells if an address is in a CIDR range. */
+export declare function cidrContains(cidr: Cidr, address: string): boolean;
+/** This function gives the class of an IP address, or `undefined` for a text that is not an IP address. */
+export declare function addressClass(address: string): AddressClass | undefined;
+/**
+ * This function tells if the internet routes to an address. A `private` address is unspecified, loopback, private,
+ * shared, link-local or unique-local. Each other address is `public`, also an address for documentation.
+ */
+export declare function addressKind(address: string): "public" | "private" | undefined;
+//# sourceMappingURL=address.d.ts.map

package/build/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","names":[],"sources":["../src/address/index.ts"],"mappings":";;YASY;;;;;;;;;;;;;;;;YAiBA;;iBAcK;WACN;WACA;WACA,QAAQ;;;qBAIN;WAAqC;WAAuB,OAAO,QAAQ;;;wBA0BxE,iBAAiB;;wBAQjB,cAAc,kBAAkB;;wBAMhC,UAAU,eAAe,OAAO;;wBAYhC,WAAW,MAAM;;iBAKhB;WACN,iBAAiB;;EAE1B,IAAI;;;wBAIU,QAAQ,iBAAiB,SAAS;;wBAclC,aAAa,MAAM,MAAM;;wBAgBzB,aAAa,kBAAkB;;;;;wBAS/B,YAAY"}

package/build/address.js

@@ -0,0 +1,172 @@
+import { BlockList, isIP } from "node:net";
+import { err, ok } from "@mark1russell7/optional";
+// src/address/index.ts
+/**
+* The IP addresses and the networks of netdiag: the family and the class of an address, CIDR ranges and sets of ranges.
+*
+* This entry uses only the module `node:net`. An IPv4 address in IPv6 form (`::ffff:192.0.2.1`) is its IPv4 address.
+*/
+/** The special-purpose ranges, as data. An address that is in no range is `public`. */
+const ADDRESS_CLASSES = [
+	{
+		cidr: "0.0.0.0/8",
+		class: "unspecified"
+	},
+	{
+		cidr: "10.0.0.0/8",
+		class: "private"
+	},
+	{
+		cidr: "100.64.0.0/10",
+		class: "shared"
+	},
+	{
+		cidr: "127.0.0.0/8",
+		class: "loopback"
+	},
+	{
+		cidr: "169.254.0.0/16",
+		class: "link-local"
+	},
+	{
+		cidr: "172.16.0.0/12",
+		class: "private"
+	},
+	{
+		cidr: "192.0.2.0/24",
+		class: "documentation"
+	},
+	{
+		cidr: "192.168.0.0/16",
+		class: "private"
+	},
+	{
+		cidr: "198.18.0.0/15",
+		class: "benchmarking"
+	},
+	{
+		cidr: "198.51.100.0/24",
+		class: "documentation"
+	},
+	{
+		cidr: "203.0.113.0/24",
+		class: "documentation"
+	},
+	{
+		cidr: "224.0.0.0/4",
+		class: "multicast"
+	},
+	{
+		cidr: "240.0.0.0/4",
+		class: "reserved"
+	},
+	{
+		cidr: "::/128",
+		class: "unspecified"
+	},
+	{
+		cidr: "::1/128",
+		class: "loopback"
+	},
+	{
+		cidr: "2001:db8::/32",
+		class: "documentation"
+	},
+	{
+		cidr: "fc00::/7",
+		class: "unique-local"
+	},
+	{
+		cidr: "fe80::/10",
+		class: "link-local"
+	},
+	{
+		cidr: "ff00::/8",
+		class: "multicast"
+	}
+];
+/** The classes of the addresses that the internet does not route to a host. */
+const NOT_ROUTED = /* @__PURE__ */ new Set([
+	"unspecified",
+	"loopback",
+	"private",
+	"shared",
+	"link-local",
+	"unique-local"
+]);
+/** This function gives the canonical form of an address: no spaces, no brackets, lower case, and IPv4 for a mapped IPv4 address. */
+function canonicalAddress(address) {
+	let text = address.trim().toLowerCase();
+	if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+	return /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(text)?.[1] ?? text;
+}
+/** This function gives the family of an IP address, or `undefined` for a text that is not an IP address. */
+function addressFamily(address) {
+	const family = isIP(canonicalAddress(address));
+	return family === 4 ? "ipv4" : family === 6 ? "ipv6" : void 0;
+}
+/** This function gives the CIDR range of a text, for example `192.0.2.0/24` or `2001:db8::/32`. An address alone is a range of one address. */
+function parseCidr(text) {
+	const slash = text.indexOf("/");
+	const address = canonicalAddress(slash === -1 ? text : text.slice(0, slash));
+	const family = addressFamily(address);
+	if (family === void 0) return err(`"${text}" is not an IP address or a CIDR range.`);
+	const max = family === "ipv4" ? 32 : 128;
+	const prefix = slash === -1 ? String(max) : text.slice(slash + 1).trim();
+	if (!/^\d{1,3}$/.test(prefix) || Number(prefix) > max) return err(`"${text}" has no prefix from 0 to ${max}.`);
+	return ok({
+		address,
+		prefix: Number(prefix),
+		family
+	});
+}
+/** This function gives the text of a CIDR range. */
+function formatCidr(cidr) {
+	return `${cidr.address}/${cidr.prefix}`;
+}
+/** This function gives the set of some CIDR ranges. */
+function cidrSet(ranges) {
+	const list = new BlockList();
+	for (const range of ranges) list.addSubnet(range.address, range.prefix, range.family);
+	return {
+		ranges: [...ranges],
+		has(address) {
+			const host = canonicalAddress(address);
+			const family = addressFamily(host);
+			return family !== void 0 && list.check(host, family);
+		}
+	};
+}
+/** This function tells if an address is in a CIDR range. */
+function cidrContains(cidr, address) {
+	return cidrSet([cidr]).has(address);
+}
+let classSets;
+function classes() {
+	classSets ??= ADDRESS_CLASSES.map((entry) => {
+		const range = parseCidr(entry.cidr);
+		if (range.tag === "err") throw new Error(range.error);
+		return {
+			class: entry.class,
+			set: cidrSet([range.value])
+		};
+	});
+	return classSets;
+}
+/** This function gives the class of an IP address, or `undefined` for a text that is not an IP address. */
+function addressClass(address) {
+	if (addressFamily(address) === void 0) return void 0;
+	return classes().find((entry) => entry.set.has(address))?.class ?? "public";
+}
+/**
+* This function tells if the internet routes to an address. A `private` address is unspecified, loopback, private,
+* shared, link-local or unique-local. Each other address is `public`, also an address for documentation.
+*/
+function addressKind(address) {
+	const found = addressClass(address);
+	if (found === void 0) return void 0;
+	return NOT_ROUTED.has(found) ? "private" : "public";
+}
+export { ADDRESS_CLASSES, addressClass, addressFamily, addressKind, canonicalAddress, cidrContains, cidrSet, formatCidr, parseCidr };
+
+//# sourceMappingURL=address.js.map

package/build/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","names":[],"sources":["../src/address/index.ts"],"sourcesContent":["/**\n * The IP addresses and the networks of netdiag: the family and the class of an address, CIDR ranges and sets of ranges.\n *\n * This entry uses only the module `node:net`. An IPv4 address in IPv6 form (`::ffff:192.0.2.1`) is its IPv4 address.\n */\nimport { BlockList, isIP } from \"node:net\";\nimport { err, ok, type Result } from \"@mark1russell7/optional\";\n\n/** The family of an IP address. */\nexport type AddressFamily = \"ipv4\" | \"ipv6\";\n\n/**\n * The class of an IP address, from the special-purpose ranges of RFC 6890.\n *\n * - `unspecified`: `0.0.0.0/8` and `::`.\n * - `loopback`: `127.0.0.0/8` and `::1`.\n * - `private`: the ranges of RFC 1918.\n * - `shared`: `100.64.0.0/10`, the carrier-grade NAT range of RFC 6598.\n * - `link-local`: `169.254.0.0/16` and `fe80::/10`.\n * - `unique-local`: `fc00::/7`, the private range of IPv6 (RFC 4193).\n * - `documentation`: the ranges of RFC 5737 and RFC 3849 for examples.\n * - `benchmarking`: `198.18.0.0/15` (RFC 2544).\n * - `multicast`: `224.0.0.0/4` and `ff00::/8`.\n * - `reserved`: `240.0.0.0/4`, with the broadcast address.\n * - `public`: each other address.\n */\nexport type AddressClass =\n  | \"unspecified\"\n  | \"loopback\"\n  | \"private\"\n  | \"shared\"\n  | \"link-local\"\n  | \"unique-local\"\n  | \"documentation\"\n  | \"benchmarking\"\n  | \"multicast\"\n  | \"reserved\"\n  | \"public\";\n\n/** A CIDR range: an address of the network and the length of its prefix. */\nexport interface Cidr {\n  readonly address: string;\n  readonly prefix: number;\n  readonly family: AddressFamily;\n}\n\n/** The special-purpose ranges, as data. An address that is in no range is `public`. */\nexport const ADDRESS_CLASSES: readonly { readonly cidr: string; readonly class: Exclude<AddressClass, \"public\"> }[] = [\n  { cidr: \"0.0.0.0/8\", class: \"unspecified\" },\n  { cidr: \"10.0.0.0/8\", class: \"private\" },\n  { cidr: \"100.64.0.0/10\", class: \"shared\" },\n  { cidr: \"127.0.0.0/8\", class: \"loopback\" },\n  { cidr: \"169.254.0.0/16\", class: \"link-local\" },\n  { cidr: \"172.16.0.0/12\", class: \"private\" },\n  { cidr: \"192.0.2.0/24\", class: \"documentation\" },\n  { cidr: \"192.168.0.0/16\", class: \"private\" },\n  { cidr: \"198.18.0.0/15\", class: \"benchmarking\" },\n  { cidr: \"198.51.100.0/24\", class: \"documentation\" },\n  { cidr: \"203.0.113.0/24\", class: \"documentation\" },\n  { cidr: \"224.0.0.0/4\", class: \"multicast\" },\n  { cidr: \"240.0.0.0/4\", class: \"reserved\" },\n  { cidr: \"::/128\", class: \"unspecified\" },\n  { cidr: \"::1/128\", class: \"loopback\" },\n  { cidr: \"2001:db8::/32\", class: \"documentation\" },\n  { cidr: \"fc00::/7\", class: \"unique-local\" },\n  { cidr: \"fe80::/10\", class: \"link-local\" },\n  { cidr: \"ff00::/8\", class: \"multicast\" },\n];\n\n/** The classes of the addresses that the internet does not route to a host. */\nconst NOT_ROUTED: ReadonlySet<AddressClass> = new Set([\"unspecified\", \"loopback\", \"private\", \"shared\", \"link-local\", \"unique-local\"]);\n\n/** This function gives the canonical form of an address: no spaces, no brackets, lower case, and IPv4 for a mapped IPv4 address. */\nexport function canonicalAddress(address: string): string {\n  let text = address.trim().toLowerCase();\n  if (text.startsWith(\"[\") && text.endsWith(\"]\")) text = text.slice(1, -1);\n  const mapped = /^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/.exec(text)?.[1];\n  return mapped ?? text;\n}\n\n/** This function gives the family of an IP address, or `undefined` for a text that is not an IP address. */\nexport function addressFamily(address: string): AddressFamily | undefined {\n  const family = isIP(canonicalAddress(address));\n  return family === 4 ? \"ipv4\" : family === 6 ? \"ipv6\" : undefined;\n}\n\n/** This function gives the CIDR range of a text, for example `192.0.2.0/24` or `2001:db8::/32`. An address alone is a range of one address. */\nexport function parseCidr(text: string): Result<Cidr, string> {\n  const slash = text.indexOf(\"/\");\n  const address = canonicalAddress(slash === -1 ? text : text.slice(0, slash));\n  const family = addressFamily(address);\n  if (family === undefined) return err(`\"${text}\" is not an IP address or a CIDR range.`);\n  const max = family === \"ipv4\" ? 32 : 128;\n  const prefix = slash === -1 ? String(max) : text.slice(slash + 1).trim();\n  if (!/^\\d{1,3}$/.test(prefix) || Number(prefix) > max) return err(`\"${text}\" has no prefix from 0 to ${max}.`);\n  return ok({ address, prefix: Number(prefix), family });\n}\n\n/** This function gives the text of a CIDR range. */\nexport function formatCidr(cidr: Cidr): string {\n  return `${cidr.address}/${cidr.prefix}`;\n}\n\n/** A set of CIDR ranges. */\nexport interface CidrSet {\n  readonly ranges: readonly Cidr[];\n  /** This function tells if an address is in a range of the set. A text that is not an IP address is in no set. */\n  has(address: string): boolean;\n}\n\n/** This function gives the set of some CIDR ranges. */\nexport function cidrSet(ranges: readonly Cidr[]): CidrSet {\n  const list = new BlockList();\n  for (const range of ranges) list.addSubnet(range.address, range.prefix, range.family);\n  return {\n    ranges: [...ranges],\n    has(address) {\n      const host = canonicalAddress(address);\n      const family = addressFamily(host);\n      return family !== undefined && list.check(host, family);\n    },\n  };\n}\n\n/** This function tells if an address is in a CIDR range. */\nexport function cidrContains(cidr: Cidr, address: string): boolean {\n  return cidrSet([cidr]).has(address);\n}\n\nlet classSets: readonly { readonly class: Exclude<AddressClass, \"public\">; readonly set: CidrSet }[] | undefined;\n\nfunction classes(): NonNullable<typeof classSets> {\n  classSets ??= ADDRESS_CLASSES.map((entry) => {\n    const range = parseCidr(entry.cidr);\n    if (range.tag === \"err\") throw new Error(range.error);\n    return { class: entry.class, set: cidrSet([range.value]) };\n  });\n  return classSets;\n}\n\n/** This function gives the class of an IP address, or `undefined` for a text that is not an IP address. */\nexport function addressClass(address: string): AddressClass | undefined {\n  if (addressFamily(address) === undefined) return undefined;\n  return classes().find((entry) => entry.set.has(address))?.class ?? \"public\";\n}\n\n/**\n * This function tells if the internet routes to an address. A `private` address is unspecified, loopback, private,\n * shared, link-local or unique-local. Each other address is `public`, also an address for documentation.\n */\nexport function addressKind(address: string): \"public\" | \"private\" | undefined {\n  const found = addressClass(address);\n  if (found === undefined) return undefined;\n  return NOT_ROUTED.has(found) ? \"private\" : \"public\";\n}\n"],"mappings":";;;;;;;;;AA+CA,MAAa,kBAAyG;CACpH;EAAE,MAAM;EAAa,OAAO;CAAc;CAC1C;EAAE,MAAM;EAAc,OAAO;CAAU;CACvC;EAAE,MAAM;EAAiB,OAAO;CAAS;CACzC;EAAE,MAAM;EAAe,OAAO;CAAW;CACzC;EAAE,MAAM;EAAkB,OAAO;CAAa;CAC9C;EAAE,MAAM;EAAiB,OAAO;CAAU;CAC1C;EAAE,MAAM;EAAgB,OAAO;CAAgB;CAC/C;EAAE,MAAM;EAAkB,OAAO;CAAU;CAC3C;EAAE,MAAM;EAAiB,OAAO;CAAe;CAC/C;EAAE,MAAM;EAAmB,OAAO;CAAgB;CAClD;EAAE,MAAM;EAAkB,OAAO;CAAgB;CACjD;EAAE,MAAM;EAAe,OAAO;CAAY;CAC1C;EAAE,MAAM;EAAe,OAAO;CAAW;CACzC;EAAE,MAAM;EAAU,OAAO;CAAc;CACvC;EAAE,MAAM;EAAW,OAAO;CAAW;CACrC;EAAE,MAAM;EAAiB,OAAO;CAAgB;CAChD;EAAE,MAAM;EAAY,OAAO;CAAe;CAC1C;EAAE,MAAM;EAAa,OAAO;CAAa;CACzC;EAAE,MAAM;EAAY,OAAO;CAAY;AACzC;;AAGA,MAAM,6BAAwC,IAAI,IAAI;CAAC;CAAe;CAAY;CAAW;CAAU;CAAc;AAAc,CAAC;;AAGpI,SAAgB,iBAAiB,SAAyB;CACxD,IAAI,OAAO,QAAQ,KAAK,CAAC,CAAC,YAAY;CACtC,IAAI,KAAK,WAAW,GAAG,KAAK,KAAK,SAAS,GAAG,GAAG,OAAO,KAAK,MAAM,GAAG,EAAE;CAEvE,OADe,gCAAgC,KAAK,IAAI,CAAC,GAAG,MAC3C;AACnB;;AAGA,SAAgB,cAAc,SAA4C;CACxE,MAAM,SAAS,KAAK,iBAAiB,OAAO,CAAC;CAC7C,OAAO,WAAW,IAAI,SAAS,WAAW,IAAI,SAAS,KAAA;AACzD;;AAGA,SAAgB,UAAU,MAAoC;CAC5D,MAAM,QAAQ,KAAK,QAAQ,GAAG;CAC9B,MAAM,UAAU,iBAAiB,UAAU,KAAK,OAAO,KAAK,MAAM,GAAG,KAAK,CAAC;CAC3E,MAAM,SAAS,cAAc,OAAO;CACpC,IAAI,WAAW,KAAA,GAAW,OAAO,IAAI,IAAI,KAAK,wCAAwC;CACtF,MAAM,MAAM,WAAW,SAAS,KAAK;CACrC,MAAM,SAAS,UAAU,KAAK,OAAO,GAAG,IAAI,KAAK,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;CACvE,IAAI,CAAC,YAAY,KAAK,MAAM,KAAK,OAAO,MAAM,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,4BAA4B,IAAI,EAAE;CAC7G,OAAO,GAAG;EAAE;EAAS,QAAQ,OAAO,MAAM;EAAG;CAAO,CAAC;AACvD;;AAGA,SAAgB,WAAW,MAAoB;CAC7C,OAAO,GAAG,KAAK,QAAQ,GAAG,KAAK;AACjC;;AAUA,SAAgB,QAAQ,QAAkC;CACxD,MAAM,OAAO,IAAI,UAAU;CAC3B,KAAK,MAAM,SAAS,QAAQ,KAAK,UAAU,MAAM,SAAS,MAAM,QAAQ,MAAM,MAAM;CACpF,OAAO;EACL,QAAQ,CAAC,GAAG,MAAM;EAClB,IAAI,SAAS;GACX,MAAM,OAAO,iBAAiB,OAAO;GACrC,MAAM,SAAS,cAAc,IAAI;GACjC,OAAO,WAAW,KAAA,KAAa,KAAK,MAAM,MAAM,MAAM;EACxD;CACF;AACF;;AAGA,SAAgB,aAAa,MAAY,SAA0B;CACjE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO;AACpC;AAEA,IAAI;AAEJ,SAAS,UAAyC;CAChD,cAAc,gBAAgB,KAAK,UAAU;EAC3C,MAAM,QAAQ,UAAU,MAAM,IAAI;EAClC,IAAI,MAAM,QAAQ,OAAO,MAAM,IAAI,MAAM,MAAM,KAAK;EACpD,OAAO;GAAE,OAAO,MAAM;GAAO,KAAK,QAAQ,CAAC,MAAM,KAAK,CAAC;EAAE;CAC3D,CAAC;CACD,OAAO;AACT;;AAGA,SAAgB,aAAa,SAA2C;CACtE,IAAI,cAAc,OAAO,MAAM,KAAA,GAAW,OAAO,KAAA;CACjD,OAAO,QAAQ,CAAC,CAAC,MAAM,UAAU,MAAM,IAAI,IAAI,OAAO,CAAC,CAAC,EAAE,SAAS;AACrE;;;;;AAMA,SAAgB,YAAY,SAAmD;CAC7E,MAAM,QAAQ,aAAa,OAAO;CAClC,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;CAChC,OAAO,WAAW,IAAI,KAAK,IAAI,YAAY;AAC7C"}

package/build/{diagnosis-BTa-Dfwl.js → diagnosis-a4hRzFxp.js}

@@ -1,4 +1,5 @@
 import { err, ok } from "@mark1russell7/optional";
+import { brier, classScores, confusion, wilson } from "@mark1russell7/rigor-statistics";
 // src/layer.ts
 /**
 * The layers of the network stack that netdiag examines, from the bottom to the top.
@@ -298,26 +299,28 @@ const STANDARD_FEATURES = [
 	{
 		id: "dns.answer",
 		layer: "dns",
-		summary: "The result of the DNS lookup of the name of the target.",
+		summary: "The result of the DNS lookup of the name of the target. The value unreachable tells that no DNS service listens on the resolver.",
 		values: [
 			"ok",
 			"nxdomain",
 			"servfail",
 			"refused",
-			"timeout"
+			"timeout",
+			"unreachable"
 		],
 		healthy: {
-			ok: .97,
+			ok: .965,
 			nxdomain: .01,
 			servfail: .005,
 			refused: .005,
-			timeout: .01
+			timeout: .01,
+			unreachable: .005
 		}
 	},
 	{
 		id: "dns.address",
 		layer: "dns",
-		summary: "The kind of the addresses of a public name: public, or private (RFC 1918, RFC 4193 or loopback).",
+		summary: "The kind of the addresses of a public name: public, or private (RFC 1918, RFC 6598, RFC 4193, loopback, link-local or unspecified).",
 		values: ["public", "private"],
 		healthy: {
 			public: .95,
@@ -410,7 +413,7 @@ const STANDARD_FEATURES = [
 	{
 		id: "tls.ratio",
 		layer: "tls",
-		summary: "The time of the TLS handshake divided by the time of the TCP connect: low (below 3), mid, or high (above 8).",
+		summary: "The time of the TLS handshake divided by the time of the TCP connect: low (below 3), mid, or high (8 or more).",
 		values: [
 			"low",
 			"mid",
@@ -452,7 +455,7 @@ const STANDARD_FEATURES = [
 	{
 		id: "http.ttfb",
 		layer: "http",
-		summary: "The time to the first byte divided by the time of the TCP connect: low (below 4), mid, or high (above 20).",
+		summary: "The time to the first byte divided by the time of the TCP connect: low (below 4), mid, or high (20 or more).",
 		values: [
 			"low",
 			"mid",
@@ -573,7 +576,7 @@ const STANDARD_FAULTS = [
 		summary: "The DNS resolver does not answer.",
 		step: "Use a different DNS resolver, or examine the resolver of the router.",
 		predicts: { "dns.answer": {
-			expect: "timeout",
+			expect: ["timeout", "unreachable"],
 			strength: "strong"
 		} }
 	},
@@ -805,7 +808,7 @@ const STANDARD_FAULTS = [
 ];
 /** The standard catalog: the rules of practice as the first likelihoods. Each hypothesis has the prior weight 1. */
 const STANDARD_CATALOG_SPEC = {
-	version: "1",
+	version: "2",
 	features: STANDARD_FEATURES,
 	faults: STANDARD_FAULTS
 };
@@ -815,6 +818,105 @@ const STANDARD_CATALOG = (() => {
 	if (compiled.tag === "err") throw new Error(`The standard catalog has problems: ${compiled.error.join(" ")}`);
 	return compiled.value;
 })();
-export { layerRank as _, FLOOR as a, STRENGTHS as c, diagnose as d, expand as f, isLayer as g, LAYERS as h, STANDARD_FEATURES as i, UNKNOWN as l, predictive as m, STANDARD_CATALOG_SPEC as n, NONE as o, explain as p, STANDARD_FAULTS as r, PARTS as s, STANDARD_CATALOG as t, compileCatalog as u };
+// src/diagnosis/score.ts
+/** The format of a lab record. */
+const LAB_RECORD_FORMAT = "netdiag.lab-record/1";
+/**
+* This function makes the record of one run of a lab case. The truth must be a hypothesis of the catalog, and the
+* diagnosis must have a cause.
+*/
+function labRecordOf(catalog, caseId, truth, diagnosis) {
+	if (!catalog.hypotheses.some((hypothesis) => hypothesis.id === truth)) return err(`The truth "${truth}" is not a hypothesis of the catalog ${catalog.version}.`);
+	const first = diagnosis.causes[0];
+	if (first === void 0) return err("The diagnosis has no cause.");
+	const index = diagnosis.causes.findIndex((cause) => cause.id === truth);
+	if (index < 0) return err(`The diagnosis has no cause "${truth}".`);
+	return ok({
+		format: LAB_RECORD_FORMAT,
+		case: caseId,
+		catalog: catalog.version,
+		truth,
+		predicted: first.id,
+		rank: index + 1,
+		causes: diagnosis.causes.map((cause) => ({
+			id: cause.id,
+			probability: cause.probability
+		}))
+	});
+}
+/**
+* This function scores the lab records of one catalog. The recall of a hypothesis is the part of its runs where the
+* diagnosis names it. A record of a different catalog version, or with a hypothesis that is not in the catalog, is an error.
+*/
+function scoreLab(catalog, records) {
+	const ids = catalog.hypotheses.map((hypothesis) => hypothesis.id);
+	const known = new Set(ids);
+	const problems = [];
+	records.forEach((record, i) => {
+		const name = `Record ${i} (${record.case})`;
+		if (record.format !== "netdiag.lab-record/1") problems.push(`${name} has the format "${String(record.format)}", not "${LAB_RECORD_FORMAT}".`);
+		if (record.catalog !== catalog.version) problems.push(`${name} comes from the catalog ${record.catalog}, not ${catalog.version}.`);
+		for (const id of /* @__PURE__ */ new Set([
+			record.truth,
+			record.predicted,
+			...record.causes.map((cause) => cause.id)
+		])) if (!known.has(id)) problems.push(`${name} names "${id}", which is not a hypothesis of the catalog.`);
+	});
+	if (problems.length > 0) return err(problems);
+	const table = confusion(records.map((record) => record.truth), records.map((record) => record.predicted), ids);
+	const forecasts = records.flatMap((record) => {
+		const probability = new Map(record.causes.map((cause) => [cause.id, cause.probability]));
+		return ids.map((id) => ({
+			p: probability.get(id) ?? 0,
+			hit: id === record.truth
+		}));
+	});
+	return ok({
+		catalog: catalog.version,
+		n: table.n,
+		correct: table.correct,
+		accuracy: wilson(table.correct, table.n),
+		table,
+		classes: classScores(table),
+		brier: records.length === 0 ? void 0 : brier(forecasts) * ids.length
+	});
+}
+/**
+* This function holds the recall of each hypothesis with a bar. A hypothesis passes when the lower end of its
+* recall interval is the bar or more. A bar for a hypothesis that is not in the score is an error.
+*/
+function labGate(score, bars) {
+	const problems = [];
+	const labels = new Set(score.table.labels);
+	for (const [hypothesis, bar] of Object.entries(bars)) {
+		if (!labels.has(hypothesis)) problems.push(`The bar of "${hypothesis}" is not for a hypothesis of the catalog ${score.catalog}.`);
+		if (!(bar >= 0 && bar <= 1)) problems.push(`The bar of "${hypothesis}" is ${bar}. A bar is from 0 to 1.`);
+	}
+	if (problems.length > 0) return err(problems);
+	const verdicts = [];
+	const unbarred = [];
+	for (const scores of score.classes) {
+		const bar = bars[scores.label];
+		if (bar === void 0) {
+			unbarred.push(scores.label);
+			continue;
+		}
+		const low = scores.support === 0 ? void 0 : scores.recallInterval.low;
+		const status = low === void 0 ? "no-read" : low >= bar ? "pass" : "fail";
+		verdicts.push({
+			hypothesis: scores.label,
+			status,
+			bar,
+			low,
+			support: scores.support
+		});
+	}
+	return ok({
+		pass: verdicts.length > 0 && verdicts.every((verdict) => verdict.status === "pass"),
+		verdicts,
+		unbarred
+	});
+}
+export { explain as _, STANDARD_CATALOG as a, isLayer as b, STANDARD_FEATURES as c, PARTS as d, STRENGTHS as f, expand as g, diagnose as h, scoreLab as i, FLOOR as l, compileCatalog as m, labGate as n, STANDARD_CATALOG_SPEC as o, UNKNOWN as p, labRecordOf as r, STANDARD_FAULTS as s, LAB_RECORD_FORMAT as t, NONE as u, predictive as v, layerRank as x, LAYERS as y };
 
-//# sourceMappingURL=diagnosis-BTa-Dfwl.js.map
+//# sourceMappingURL=diagnosis-a4hRzFxp.js.map