@runbooks/search 0.1.0

package/dist/stack.js

@@ -0,0 +1,164 @@
+/**
+ * Stack matching (W-20, §17, §13.3).
+ *
+ * §17's third entry point taken to its conclusion: a reader says what they have — targets
+ * and versions, the capabilities their client offers, how much risk they will accept, what
+ * supervision they enforce — and the catalog answers what applies to *them*.
+ *
+ * The privacy shape is the constraint that decides the design. **A declared stack is an
+ * infrastructure fingerprint**: postgres 14.3 and kubernetes 1.29 and a private MCP server
+ * names an organization more precisely than most of what §14 refuses to collect in a run
+ * report. So the declaration never travels. This module is a pure function over the
+ * published index, run in the reader's browser, and there is nothing here that could send
+ * one anywhere — no client, no logger, no callback.
+ *
+ * The matching itself is deliberately unclever. A range that cannot be parsed does not
+ * match rather than matching hopefully: telling somebody a procedure applies to their
+ * cluster when nobody checked is worse than telling them nothing.
+ */
+import { DEFAULT_TRUST_MIN } from "./search.js";
+const RISK_ORDER = ["read-only", "reversible-write", "destructive", "irreversible"];
+const PROFILE_ORDER = ["R0", "R1", "R2"];
+const TRUST_ORDER = ["T0", "T1", "T2", "T3", "T4"];
+/**
+ * Does this version satisfy this range?
+ *
+ * A deliberately small subset of what a version range can be: comparators over dotted
+ * numbers, joined by spaces meaning "and". Anything else is **unparseable, and unparseable
+ * does not match** — a range this cannot read is a question nobody answered, and answering
+ * it optimistically puts a procedure in front of somebody whose cluster it was never
+ * checked against.
+ */
+export function satisfies(version, range) {
+    const parts = range.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return undefined;
+    let verdict = true;
+    for (const part of parts) {
+        const match = /^(>=|<=|>|<|=)?(\d+(?:\.\d+){0,2})$/.exec(part);
+        if (!match)
+            return undefined;
+        const operator = match[1] ?? "=";
+        const compared = compare(version, match[2]);
+        const ok = operator === ">=" ? compared >= 0 :
+            operator === "<=" ? compared <= 0 :
+                operator === ">" ? compared > 0 :
+                    operator === "<" ? compared < 0 :
+                        compared === 0;
+        verdict = verdict && ok;
+    }
+    return verdict;
+}
+function compare(a, b) {
+    const left = a.split(".").map(Number);
+    const right = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const difference = (left[i] ?? 0) - (right[i] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+/**
+ * Whether a record applies to a stack, and when it does not, why.
+ *
+ * The refusals are named because "no results" is the least useful thing a catalog can say
+ * to somebody who has just described their environment: a reader who is told *their client
+ * only enforces R0* knows what to change, and a reader shown an empty list concludes the
+ * catalog is empty.
+ */
+export function applicability(record, stack) {
+    const declared = Object.keys(stack.targets);
+    const matchedTargets = record.targets.filter((target) => {
+        if (!declared.includes(target))
+            return false;
+        const range = record.applies_to?.[target];
+        const version = stack.targets[target];
+        if (!range || !version)
+            return true;
+        // Unparseable or unsatisfied both fail: see `satisfies`.
+        return satisfies(version, range) === true;
+    });
+    if (declared.length > 0 && matchedTargets.length === 0) {
+        const versioned = record.targets.filter((target) => declared.includes(target));
+        if (versioned.length > 0) {
+            const ranges = versioned
+                .map((target) => `${target} ${record.applies_to?.[target] ?? "any"}`)
+                .join(", ");
+            return {
+                applies: false,
+                why: `Your versions are outside what this declares: it applies to ${ranges}.`,
+            };
+        }
+        return {
+            applies: false,
+            why: `It is for ${record.targets.join(", ") || "no declared target"}, which is not in your stack.`,
+        };
+    }
+    /**
+     * §13.3, and the one refusal that is about safety rather than relevance: a client that
+     * enforces R0 is not shown a procedure demanding R2. Ranked low, it would still be
+     * clicked; refused, it says what the reader would have to change.
+     */
+    const needs = record.min_runtime_profile ?? "R0";
+    const enforces = stack.runtimeProfile ?? "R0";
+    if (PROFILE_ORDER.indexOf(needs) > PROFILE_ORDER.indexOf(enforces)) {
+        return {
+            applies: false,
+            why: `It requires ${needs} supervision and your client enforces ${enforces}. This is a refusal rather than a low rank: a procedure that outruns its supervisor is the failure the execution contract exists to prevent.`,
+        };
+    }
+    const missing = record.capabilities.filter((capability) => !stack.capabilities.includes(capability));
+    if (missing.length > 0) {
+        return {
+            applies: false,
+            why: `You have not offered ${missing.join(", ")}. Every capability a procedure declares has to be available, or it stops halfway — and part of a destructive procedure is a state nobody designed.`,
+        };
+    }
+    if (stack.riskCeiling && RISK_ORDER.indexOf(record.risk) > RISK_ORDER.indexOf(stack.riskCeiling)) {
+        return {
+            applies: false,
+            why: `Its highest risk is ${record.risk} and you set a ceiling of ${stack.riskCeiling}.`,
+        };
+    }
+    if (stack.execution && record.execution && stack.execution !== record.execution) {
+        return { applies: false, why: `It is ${record.execution} and you asked for ${stack.execution}.` };
+    }
+    const floor = stack.trustMin ?? DEFAULT_TRUST_MIN;
+    if (TRUST_ORDER.indexOf(record.trust) < TRUST_ORDER.indexOf(floor)) {
+        return {
+            applies: false,
+            why: stack.trustMin
+                ? `It is ${record.trust} and you set a floor of ${stack.trustMin}.`
+                : `It is ${record.trust}, below the ${DEFAULT_TRUST_MIN} this shows by default. Lower the floor to see it.`,
+        };
+    }
+    return { applies: true, matchedTargets };
+}
+/**
+ * What applies, ranked by applicability and then by trust.
+ *
+ * Applicability first because relevance is what was asked for; trust second because
+ * between two procedures that both fit, the one somebody has verified is the better
+ * answer. Ties break on the ref, so two builds of the same catalog agree.
+ */
+export function matchStack(records, stack) {
+    return records
+        .map((record) => ({ record, verdict: applicability(record, stack) }))
+        .filter((entry) => entry.verdict.applies)
+        .map((entry) => ({ record: entry.record, matchedTargets: entry.verdict.matchedTargets }))
+        .sort((a, b) => {
+        if (a.matchedTargets.length !== b.matchedTargets.length) {
+            return b.matchedTargets.length - a.matchedTargets.length;
+        }
+        const trust = TRUST_ORDER.indexOf(b.record.trust) - TRUST_ORDER.indexOf(a.record.trust);
+        return trust !== 0 ? trust : a.record.ref < b.record.ref ? -1 : 1;
+    });
+}
+/** Everything that did not apply, with the reason: an empty list explains nothing. */
+export function excluded(records, stack) {
+    return records
+        .map((record) => ({ record, verdict: applicability(record, stack) }))
+        .filter((entry) => !entry.verdict.applies)
+        .map((entry) => ({ ref: entry.record.ref, why: entry.verdict.why }));
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@runbooks/search",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Search over the prebuilt index: symptom, facet and capability.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runbooks-directory/runbooks.directory"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  }
+}