@milaboratories/pl-middle-layer 1.66.19 → 1.67.1

package/src/block_registry/location_provider.ts

@@ -0,0 +1,124 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { BlockPackLocationReference } from "@milaboratories/pl-model-common";
+import { parseBlockPackLocation } from "@milaboratories/pl-model-common";
+import type { BlockPackSpec } from "@milaboratories/pl-model-middle-layer";
+import type { BlockPackDescriptionAbsolute } from "@platforma-sdk/block-tools";
+import { loadPackDescription, loadPackDescriptionFromManifest } from "@platforma-sdk/block-tools";
+import type { LocationResolution } from "../model/template_resolve";
+
+/**
+ * Read the block a template entry's `location` points at.
+ *
+ * The filesystem half of {@link BlockPackProvider}, and the reason a project built from
+ * locally developed blocks can be exported and applied without publishing anything. No
+ * registry is involved and nothing is searched: the entry named a place.
+ *
+ * Only `file:` is served. The document's grammar admits any scheme so that a template
+ * stays readable by a consumer that can fetch more than this one can, and an unknown
+ * scheme is reported rather than treated as a missing block — "I cannot read this" and
+ * "there is nothing there" send the reader to different places.
+ */
+export async function resolveBlockPackLocation(
+  location: BlockPackLocationReference,
+): Promise<LocationResolution> {
+  if (parseBlockPackLocation(location).scheme !== "file") {
+    return { ok: false, reason: "unsupported-scheme" };
+  }
+
+  // The value is a URL, never a path: `fileURLToPath` is what turns `%20` back into the
+  // space that was in the folder name. Reading `pathname` directly would look right and
+  // fail on any path with a space in it.
+  const dir = fileURLToPath(location);
+
+  const found = await readPackAt(dir);
+  if (found === undefined) {
+    return (await exists(dir))
+      ? { ok: false, reason: "not-a-block" }
+      : { ok: false, reason: "not-found" };
+  }
+
+  return { ok: true, spec: found.spec, title: found.description.meta.title };
+}
+
+/** One readable block pack: which spec addresses it, and what it declares. */
+type FoundPack = {
+  readonly spec: BlockPackSpec;
+  readonly description: BlockPackDescriptionAbsolute;
+};
+
+/**
+ * Identify what kind of block pack is at `dir`, by looking rather than by being told.
+ *
+ * Two layouts can sit behind one `location`, and they anchor differently — a packed
+ * block at the folder holding its `manifest.json`, a source block at the folder holding
+ * the `package.json` that names its components. The document deliberately records only
+ * the URI, so the layout is established here, where the filesystem is: encoding it in
+ * the file instead would freeze today's two shapes into the format, and a template
+ * written last month would name a layout that has since moved.
+ *
+ * A packed layout is checked first because it is the more specific one: a facade
+ * package's own folder holds `package.json` and, once packed, `block-pack/` beside it
+ * — never `manifest.json` directly.
+ *
+ * When neither matches, the two conventional subfolders are tried. Those are the same
+ * names the dev-block scanner probes, so a hand-written entry may name the block's own
+ * folder rather than the package inside it. Export never emits these: it writes the
+ * anchor the loader accepts, so there is nothing to guess on a round trip.
+ */
+async function readPackAt(dir: string): Promise<FoundPack | undefined> {
+  const direct = await readPackExactlyAt(dir);
+  if (direct !== undefined) return direct;
+
+  for (const subfolder of ["block", "meta"]) {
+    const nested = await readPackExactlyAt(path.join(dir, subfolder));
+    if (nested !== undefined) return nested;
+  }
+
+  return undefined;
+}
+
+async function readPackExactlyAt(dir: string): Promise<FoundPack | undefined> {
+  if (await exists(path.join(dir, "manifest.json"))) {
+    const description = await loadPackDescriptionFromManifest(dir);
+    return {
+      // The pack directory is what the preparer expects to be handed, and it is where
+      // the manifest was just read from — not something reconstructed from a parent.
+      spec: { type: "from-pack-v2", packUrl: pathToFileURL(dir).href },
+      description,
+    };
+  }
+
+  if (await hasBlockDescription(path.join(dir, "package.json"))) {
+    const description = await loadPackDescription(dir);
+    return { spec: { type: "dev-v2", folder: dir }, description };
+  }
+
+  return undefined;
+}
+
+/**
+ * Whether this `package.json` describes a block at all.
+ *
+ * Checked before handing the folder to the loader so that an ordinary npm package —
+ * anything with a `package.json` and no block description — comes back as "not a
+ * block" rather than as a thrown parse failure from inside the loader.
+ */
+async function hasBlockDescription(packageJsonPath: string): Promise<boolean> {
+  try {
+    const parsed: unknown = JSON.parse(await fsp.readFile(packageJsonPath, "utf-8"));
+    return typeof parsed === "object" && parsed !== null && "block" in parsed;
+  } catch {
+    return false;
+  }
+}
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await fsp.stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/block_registry/registry.ts

@@ -14,11 +14,13 @@ import type {
   BlockPackId,
   BlockPackListing,
   BlockPackOverview,
+  BlockPackFromRegistryV2,
   RegistryEntry,
   RegistryStatus,
   SingleBlockPackOverview,
 } from "@milaboratories/pl-model-middle-layer";
 import { AnyChannel, StableChannel } from "@milaboratories/pl-model-middle-layer";
+import type { BlockKindReference } from "@milaboratories/pl-model-common";
 
 async function getFileContent(path: string) {
   try {
@@ -301,4 +303,24 @@ export class BlockPackRegistry {
     const reg = this.v2Provider.getRegistry(regSpec.url);
     return await reg.getSpecificOverview(blockId, channel);
   }
+
+  /**
+   * Resolve a block-kind reference (`{name}@{selector}`) against a `remote-v2`
+   * registry to a concrete `from-registry-v2` block spec. Thin facade cloned
+   * from {@link getOverview}: resolve `registryId` → assert `remote-v2` →
+   * delegate to the reader's pure-core-backed `resolveKind`. All version-math
+   * lives in `@platforma-sdk/block-tools` (no backend involvement).
+   */
+  public async resolveKind(
+    registryId: string,
+    ref: BlockKindReference,
+    { allowUnstable }: { allowUnstable: boolean },
+  ): Promise<BlockPackFromRegistryV2> {
+    const regSpec = this.registries.find((reg) => reg.id === registryId)?.spec;
+    if (!regSpec) throw new Error(`Registry with id "${registryId}" not found`);
+    if (regSpec.type !== "remote-v2")
+      throw new Error(`Only "remote-v2" registries support block-kind resolution.`);
+    const reg = this.v2Provider.getRegistry(regSpec.url);
+    return await reg.resolveKind(ref, { allowUnstable });
+  }
 }

package/src/block_registry/template_provider.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, test } from "vitest";
+import { KindResolutionError } from "@platforma-sdk/block-tools";
+import type {
+  BlockPackFromRegistryV2,
+  BlockPackId,
+  RegistryEntry,
+  SingleBlockPackOverview,
+} from "@milaboratories/pl-model-middle-layer";
+import type { BlockKindSelectorReference } from "@milaboratories/pl-model-common";
+import type { MiLogger } from "@milaboratories/ts-helpers";
+import type { KindAwareRegistry } from "./template_provider";
+import { kindCapableRegistryIds, templateBlockPackProvider } from "./template_provider";
+
+/**
+ * The registry-backed provider, driven against a fake registry.
+ *
+ * Everything specific to this adapter is in what it does with two registry answers:
+ * which registries it asks, in what order, which failure it reports when they disagree,
+ * and where the block's title comes from. None of that needs a registry to check.
+ */
+
+const KIND = "@platforma-open/milaboratories.demo.kind@^1.0.0" as BlockKindSelectorReference;
+
+const blockId = (name: string, version = "1.2.3"): BlockPackId => ({
+  organization: "milaboratories",
+  name,
+  version,
+});
+
+const specIn = (registryUrl: string, id: BlockPackId): BlockPackFromRegistryV2 => ({
+  type: "from-registry-v2",
+  registryUrl,
+  id,
+  channel: "stable",
+});
+
+const overviewOf = (registryUrl: string, id: BlockPackId, title: string): SingleBlockPackOverview =>
+  ({ id, meta: { title }, spec: specIn(registryUrl, id) }) as unknown as SingleBlockPackOverview;
+
+const silent: MiLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as unknown as MiLogger;
+
+/**
+ * A registry whose per-registry answers are scripted.
+ *
+ * @param answers Keyed by registry id. A `KindResolutionError` reason stands for "this
+ *   registry cannot satisfy the kind"; anything else thrown stands for a read failure
+ */
+function fakeRegistry(answers: {
+  kind?: Record<string, BlockPackId | KindResolutionError | Error>;
+  overview?: Record<string, Record<string, string>>;
+}) {
+  const kindCalls: { registryId: string; ref: string; allowUnstable: boolean }[] = [];
+  const overviewCalls: { registryId: string; id: BlockPackId; channel: string }[] = [];
+
+  const registry: KindAwareRegistry = {
+    resolveKind: (registryId, ref, options) => {
+      kindCalls.push({ registryId, ref, allowUnstable: options.allowUnstable });
+      const answer = answers.kind?.[registryId];
+      if (answer === undefined) {
+        return Promise.reject(new KindResolutionError("no-matching-kind-version", ref));
+      }
+      if (answer instanceof Error) return Promise.reject(answer);
+      return Promise.resolve(specIn(`https://${registryId}`, answer));
+    },
+    getOverview: (registryId, id, channel) => {
+      overviewCalls.push({ registryId, id, channel });
+      const title = answers.overview?.[registryId]?.[id.name];
+      if (title === undefined) return Promise.reject(new Error("no such manifest"));
+      return Promise.resolve(overviewOf(`https://${registryId}`, id, title));
+    },
+  };
+
+  return { registry, kindCalls, overviewCalls };
+}
+
+const providerOver = (registry: KindAwareRegistry, registryIds: string[]) =>
+  templateBlockPackProvider({ registry, registryIds, logger: silent });
+
+describe("kindCapableRegistryIds", () => {
+  const entries: RegistryEntry[] = [
+    { id: "main", spec: { type: "remote-v2", url: "https://main" } },
+    { id: "local:{/w/blocks}", spec: { type: "local-dev", path: "/w/blocks" } },
+    { id: "extra", spec: { type: "remote-v2", url: "https://extra" } },
+  ];
+
+  test("keeps the remote registries, in configured order", () => {
+    expect(kindCapableRegistryIds(entries)).toEqual(["main", "extra"]);
+  });
+
+  test("drops a dev registry, which can never answer a kind", () => {
+    // Dev packets have no manifest and no kind publication, and every template entry
+    // names a kind — so asking is not a fallback, it is a guaranteed failure that would
+    // muddy the reported reason.
+    expect(kindCapableRegistryIds([entries[1]])).toEqual([]);
+  });
+});
+
+describe("byKind", () => {
+  test("resolves through the registry and reports the block's published title", async () => {
+    const { registry, kindCalls, overviewCalls } = fakeRegistry({
+      kind: { main: blockId("demo") },
+      overview: { main: { demo: "Demo Block" } },
+    });
+
+    const outcome = await providerOver(registry, ["main"]).byKind(KIND, { allowUnstable: false });
+
+    expect(outcome).toEqual({
+      ok: true,
+      spec: specIn("https://main", blockId("demo")),
+      title: "Demo Block",
+    });
+    // The projection first, then the manifest of the block it picked.
+    expect(kindCalls).toEqual([{ registryId: "main", ref: KIND, allowUnstable: false }]);
+    expect(overviewCalls).toEqual([{ registryId: "main", id: blockId("demo"), channel: "stable" }]);
+  });
+
+  test("passes the selector through unchanged", async () => {
+    // The facade's parameter is typed as an exact reference, but resolution parses the
+    // version segment as a selector — so `^1.0.0` must arrive verbatim, not normalized.
+    const { registry, kindCalls } = fakeRegistry({
+      kind: { main: blockId("demo") },
+      overview: { main: { demo: "Demo Block" } },
+    });
+
+    await providerOver(registry, ["main"]).byKind(KIND, { allowUnstable: true });
+
+    expect(kindCalls[0].ref).toBe("@platforma-open/milaboratories.demo.kind@^1.0.0");
+    expect(kindCalls[0].allowUnstable).toBe(true);
+  });
+
+  test("falls through to the next registry, first hit winning", async () => {
+    const { registry, kindCalls } = fakeRegistry({
+      kind: { extra: blockId("demo") },
+      overview: { extra: { demo: "Demo Block" } },
+    });
+
+    const outcome = await providerOver(registry, ["main", "extra"]).byKind(KIND, {
+      allowUnstable: false,
+    });
+
+    expect(outcome.ok).toBe(true);
+    expect(kindCalls.map((c) => c.registryId)).toEqual(["main", "extra"]);
+  });
+
+  test("stops at the first registry that answers", async () => {
+    const { registry, kindCalls } = fakeRegistry({
+      kind: { main: blockId("demo"), extra: blockId("demo") },
+      overview: { main: { demo: "From Main" }, extra: { demo: "From Extra" } },
+    });
+
+    const outcome = await providerOver(registry, ["main", "extra"]).byKind(KIND, {
+      allowUnstable: false,
+    });
+
+    expect(outcome.ok && outcome.title).toBe("From Main");
+    expect(kindCalls.map((c) => c.registryId)).toEqual(["main"]);
+  });
+
+  test("reports the failure that got furthest when registries disagree", async () => {
+    // One registry has never heard of the kind, the other has it but only as a
+    // pre-release. Reporting the first would tell the reader to check their spelling,
+    // when the actual way out is to import again with unstable allowed.
+    const { registry } = fakeRegistry({
+      kind: {
+        main: new KindResolutionError("no-matching-kind-version", KIND),
+        extra: new KindResolutionError("no-stable-implementation", KIND),
+      },
+    });
+
+    const outcome = await providerOver(registry, ["main", "extra"]).byKind(KIND, {
+      allowUnstable: false,
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "no-stable-implementation" });
+  });
+
+  test("no registry knowing the kind is not-found, not an error", async () => {
+    const { registry } = fakeRegistry({});
+
+    const outcome = await providerOver(registry, ["main", "extra"]).byKind(KIND, {
+      allowUnstable: false,
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "no-matching-kind-version" });
+  });
+
+  test("no registries at all is not-found rather than a crash", async () => {
+    // Reachable: an environment configured with only dev registries.
+    const { registry, kindCalls } = fakeRegistry({});
+
+    const outcome = await providerOver(registry, []).byKind(KIND, { allowUnstable: false });
+
+    expect(outcome).toEqual({ ok: false, reason: "no-matching-kind-version" });
+    expect(kindCalls).toEqual([]);
+  });
+
+  test("an unreadable registry propagates instead of reading as not-found", async () => {
+    // An outage is not a statement about the file, and reporting it as "no such kind"
+    // would send the reader to edit a file that is correct.
+    const { registry } = fakeRegistry({ kind: { main: new Error("ECONNREFUSED") } });
+
+    await expect(
+      providerOver(registry, ["main"]).byKind(KIND, { allowUnstable: false }),
+    ).rejects.toThrow("ECONNREFUSED");
+  });
+
+  test("a picked block whose manifest cannot be read propagates too", async () => {
+    // The kind resolved, so this is not a resolution failure — the registry is
+    // inconsistent or unreachable, and either way the file is not at fault.
+    const { registry } = fakeRegistry({ kind: { main: blockId("demo") } });
+
+    await expect(
+      providerOver(registry, ["main"]).byKind(KIND, { allowUnstable: false }),
+    ).rejects.toThrow("no such manifest");
+  });
+});
+
+describe("byExactVersion", () => {
+  test("reads the pinned version's manifest for both its spec and its title", async () => {
+    const { registry, overviewCalls } = fakeRegistry({
+      overview: { main: { demo: "Demo Block" } },
+    });
+
+    const outcome = await providerOver(registry, ["main"]).byExactVersion(blockId("demo", "2.0.1"));
+
+    expect(outcome).toEqual({
+      ok: true,
+      spec: specIn("https://main", blockId("demo", "2.0.1")),
+      title: "Demo Block",
+    });
+    expect(overviewCalls[0].channel).toBe("stable");
+  });
+
+  test("tries every registry before giving up", async () => {
+    const { registry, overviewCalls } = fakeRegistry({ overview: { extra: { demo: "Demo" } } });
+
+    const outcome = await providerOver(registry, ["main", "extra"]).byExactVersion(blockId("demo"));
+
+    expect(outcome.ok).toBe(true);
+    expect(overviewCalls.map((c) => c.registryId)).toEqual(["main", "extra"]);
+  });
+
+  test("a version no registry has is reported, not thrown", async () => {
+    // The entry pinned it, so this is a statement about the file — and resolution turns
+    // it into the message offering both ways out.
+    const { registry } = fakeRegistry({});
+
+    expect(await providerOver(registry, ["main"]).byExactVersion(blockId("gone", "9.9.9"))).toEqual(
+      { ok: false, reason: "no-such-block-version" },
+    );
+  });
+
+  test("every registry that could not answer is logged", async () => {
+    // The reader throws the same way for an absent block and an unreadable one, so the
+    // fallback cannot tell them apart. The log is the only place the reason survives.
+    const lines: string[] = [];
+    const logger = { info: (m: string) => lines.push(m), warn: () => {}, error: () => {} };
+    const { registry } = fakeRegistry({});
+
+    await templateBlockPackProvider({
+      registry,
+      registryIds: ["main", "extra"],
+      logger: logger as unknown as MiLogger,
+    }).byExactVersion(blockId("gone", "9.9.9"));
+
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toContain("milaboratories/gone 9.9.9");
+    expect(lines[0]).toContain("'main'");
+    expect(lines[0]).toContain("no such manifest");
+  });
+});

package/src/block_registry/template_provider.ts

@@ -0,0 +1,168 @@
+import { KindResolutionError } from "@platforma-sdk/block-tools";
+import type {
+  BlockPackFromRegistryV2,
+  BlockPackId,
+  RegistryEntry,
+  SingleBlockPackOverview,
+} from "@milaboratories/pl-model-middle-layer";
+import { StableChannel } from "@milaboratories/pl-model-middle-layer";
+import type { BlockKindReference } from "@milaboratories/pl-model-common";
+import type { MiLogger } from "@milaboratories/ts-helpers";
+import { ensureError } from "@platforma-sdk/model";
+import type { BlockPackProvider, ExactResolution, KindResolution } from "../model/template_resolve";
+import { resolveBlockPackLocation } from "./location_provider";
+
+/**
+ * The part of {@link BlockPackRegistry} a template's provider uses.
+ *
+ * Structural, so the provider can be exercised without a registry, a network or a
+ * configured environment — and so it is obvious that these two calls are the entire
+ * dependency.
+ */
+export type KindAwareRegistry = {
+  resolveKind: (
+    registryId: string,
+    ref: BlockKindReference,
+    options: { allowUnstable: boolean },
+  ) => Promise<BlockPackFromRegistryV2>;
+  getOverview: (
+    registryId: string,
+    blockId: BlockPackId,
+    channel: string,
+  ) => Promise<SingleBlockPackOverview>;
+};
+
+/**
+ * The ids of the configured registries a template can be resolved against, in the order
+ * they should be consulted.
+ *
+ * Answers the standing "which registry" question, and answers it by capability rather
+ * than by preference: kinds are published to the `kinds/` tree of a `remote-v2`
+ * registry, so no other registry type can satisfy an entry at all. A `local-dev`
+ * registry serves dev packets, which have no manifest and no kind publication — every
+ * template entry names a kind, so such a registry can never answer one.
+ *
+ * Configured order is kept: it is the order the environment chose, and the first
+ * registry that has the kind wins. Nothing here dedupes a kind published to two
+ * registries — with the search stopping at the first hit, the earlier registry is
+ * simply the answer.
+ */
+export function kindCapableRegistryIds(entries: readonly RegistryEntry[]): string[] {
+  return entries.filter((entry) => entry.spec.type === "remote-v2").map((entry) => entry.id);
+}
+
+/**
+ * A {@link BlockPackProvider} over the configured block registries.
+ *
+ * The adapter between the import path's port and what the registry layer already does:
+ * `resolveKind` walks a kind's projection and picks an implementing block,
+ * `getOverview` reads one block's manifest. Both live in the registry; the port exists
+ * so that resolution can be tested without one, and so that which registries to consult
+ * stays an environment decision.
+ *
+ * Both routes also return the block's published title, because both have to read a
+ * manifest to produce a spec anyway and nothing downstream can recover it. On the pinned
+ * route it is free; on the kind route it costs one manifest read after the projection.
+ *
+ * @param registryIds Registries to consult, in order — see {@link kindCapableRegistryIds}
+ * @param logger Where a registry that could not answer is recorded. A read failure and
+ *   an absent block are indistinguishable here (the reader throws for both), so the
+ *   fallback to the next registry has to swallow the reason; this is the only place it
+ *   survives
+ */
+export function templateBlockPackProvider(deps: {
+  readonly registry: KindAwareRegistry;
+  readonly registryIds: readonly string[];
+  readonly logger: MiLogger;
+}): BlockPackProvider {
+  const { registry, registryIds, logger } = deps;
+
+  return {
+    byKind: async (kind, options): Promise<KindResolution> => {
+      let furthest: KindResolutionFailure | undefined;
+
+      for (const registryId of registryIds) {
+        try {
+          // The selector brand is widened here, deliberately and in one place. The
+          // facade types this parameter as an exact `{name}@X.Y.Z` reference, but its
+          // implementation passes the version segment to the selector parser, so
+          // `~`/`^` resolve correctly — the type is narrower than the behaviour. Until
+          // the facade takes the selector brand, the cast is the honest way to say so.
+          const spec = await registry.resolveKind(
+            registryId,
+            kind as unknown as BlockKindReference,
+            options,
+          );
+          // Read back the manifest of the block the projection picked, in the channel it
+          // was picked from. `channel` is optional on the spec and the resolver always
+          // fills it, so the fallback is unreachable — it exists because the channel only
+          // decides where future update suggestions come from, and `stable` is the answer
+          // that surprises nobody.
+          const overview = await registry.getOverview(
+            registryId,
+            spec.id,
+            spec.channel ?? StableChannel,
+          );
+          return { ok: true, spec, title: overview.meta.title };
+        } catch (e) {
+          if (!(e instanceof KindResolutionError)) {
+            // Not an answer about this kind: an unreadable registry, or a registry that
+            // does not serve kinds at all. Falling through would report "no such kind"
+            // for what is really an outage, so it propagates instead. (The second case
+            // is unreachable through `kindCapableRegistryIds`, which filters by type.)
+            throw e;
+          }
+          furthest = furthestFailure(furthest, e.reason);
+        }
+      }
+
+      return { ok: false, reason: furthest ?? "no-matching-kind-version" };
+    },
+
+    // No registry is consulted for a located entry, and none of this adapter's
+    // registry knowledge applies to it — which is why it is a straight delegation.
+    byLocation: resolveBlockPackLocation,
+
+    byExactVersion: async (id): Promise<ExactResolution> => {
+      for (const registryId of registryIds) {
+        try {
+          // `stable` is recorded on the spec as the channel to watch for updates in.
+          // The entry pinned this exact version, so nothing is being chosen here — the
+          // channel only decides where a future update suggestion would come from.
+          const overview = await registry.getOverview(registryId, id, StableChannel);
+          return { ok: true, spec: overview.spec, title: overview.meta.title };
+        } catch (e) {
+          logger.info(
+            `template apply: block ${id.organization}/${id.name} ${id.version} not read ` +
+              `from registry '${registryId}': ${ensureError(e).message}`,
+          );
+        }
+      }
+
+      return { ok: false, reason: "no-such-block-version" };
+    },
+  };
+}
+
+type KindResolutionFailure = Extract<KindResolution, { ok: false }>["reason"];
+
+/**
+ * The more informative of two failures across registries.
+ *
+ * With several registries consulted, the reasons can differ — one has never heard of the
+ * kind, another has it but only as a pre-release. Reporting the first would tell the
+ * reader to check their spelling when the real answer is "import again with unstable
+ * allowed", so the one that got furthest wins.
+ */
+function furthestFailure(
+  current: KindResolutionFailure | undefined,
+  next: KindResolutionFailure,
+): KindResolutionFailure {
+  const rank: Record<KindResolutionFailure, number> = {
+    "no-matching-kind-version": 0,
+    "no-implementation": 1,
+    "no-stable-implementation": 2,
+  };
+  if (current === undefined) return next;
+  return rank[next] > rank[current] ? next : current;
+}