@telorun/analyzer 0.61.0 → 0.62.1

package/src/validate-identifier-names.ts

@@ -0,0 +1,173 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import type { AliasResolver } from "./alias-resolver.js";
+import type { CallGraph } from "./call-graph.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import {
+  TYPE_LEVEL_DOC_KINDS,
+  checkName,
+  type NameLevel,
+  type NameViolation,
+} from "./identifier-name.js";
+import { type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Every author-written name in one pass — resource instances, kinds, modules,
+ * import aliases, step names and `variables` / `secrets` / `ports` keys. The
+ * rules and their rationale are in `identifier-name.ts`; this file only decides
+ * what each name IS and where to report it.
+ *
+ * One pass rather than a check bolted onto each surface's own validator: the
+ * rule is identical everywhere, and seven copies of it would drift the way the
+ * dot rule already had (enforced for resources, unenforced for steps, aliases
+ * and config declarations, which reach CEL through the same identifier space).
+ *
+ * **Step names come from the call graph, never from a walk of our own.** The
+ * graph already owns the analyzer's only step-array recursion and carries each
+ * step's name, owner and concrete path, which is exactly what a diagnostic
+ * needs. Re-walking would be a second answer to "what steps exist".
+ *
+ * **Scoped to the entry's own modules, at every tier including the errors.** A
+ * published dependency's naming is not the consumer's to fix, and reporting an
+ * error they cannot act on is worse than not reporting it — the standing
+ * precedent of `X_TELO_REF_UNRESOLVED` and `validate-extends`. The library's
+ * own author sees all of it when their module is analyzed as a root.
+ *
+ * Browser-safe.
+ */
+export function validateIdentifierNames(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  rootModules: Set<string>,
+  graph: CallGraph,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  for (const manifest of manifests) {
+    const metadata = manifest.metadata as Record<string, unknown> | undefined;
+    const name = typeof metadata?.name === "string" ? metadata.name : undefined;
+    if (!manifest.kind || !name) continue;
+
+    // A name synthesized by inline extraction (`TestAdd_steps_0_invoke`) is
+    // derived from the author's own names, not written — reporting its shape
+    // would blame them for a spelling this pass's own pipeline chose.
+    if (metadata?.xTeloOrigin) continue;
+
+    const ownModule = metadata?.module as string | undefined;
+    if (ownModule && !rootModules.has(ownModule)) continue;
+
+    const level = levelFor(manifest, registry, aliases);
+    push(out, checkName(name, level, surfaceFor(manifest.kind)), {
+      kind: manifest.kind,
+      name,
+      filePath: metadata?.source as string | undefined,
+      path: "metadata.name",
+    });
+
+    // The module doc's config contract. Each key becomes `variables.<key>` /
+    // `secrets.<key>` / `ports.<key>` in CEL, so it lives in the same
+    // identifier space as a resource name and breaks the same way. An
+    // import's `variables:` / `secrets:` are deliberately NOT checked — those
+    // keys are the imported library's declarations, so a violation there is
+    // the library author's, reported when their module is analyzed as a root.
+    if (manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library") {
+      for (const field of ["variables", "secrets", "ports"] as const) {
+        const block = (manifest as Record<string, unknown>)[field];
+        if (!block || typeof block !== "object" || Array.isArray(block)) continue;
+        for (const key of Object.keys(block as Record<string, unknown>)) {
+          push(out, checkName(key, "value", `${singular(field)} name`), {
+            kind: manifest.kind,
+            name,
+            filePath: metadata?.source as string | undefined,
+            path: `${field}.${key}`,
+          });
+        }
+      }
+    }
+  }
+
+  for (const node of graph.nodes.values()) {
+    if (node.type !== "step" || !node.name) continue;
+    const owner = graph.nodes.get(node.owner);
+    if (owner?.type !== "resource") continue;
+    const ownerMeta = owner.manifest.metadata as Record<string, unknown> | undefined;
+    if (ownerMeta?.xTeloOrigin) continue;
+    const ownModule = ownerMeta?.module as string | undefined;
+    if (ownModule && !rootModules.has(ownModule)) continue;
+
+    push(out, checkName(node.name, "value", "step name"), {
+      kind: owner.kind,
+      name: owner.name,
+      filePath: ownerMeta?.source as string | undefined,
+      path: `${node.path}.name`,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * A resource instance is value-level, EXCEPT when its capability is
+ * `Telo.Type`: a named shape has no runtime instance, is referenced from
+ * `inputType:` / `outputType:` type slots and resolves as
+ * `telo:<module>/<Name>`, so its name denotes a type despite being declared as
+ * a resource. Capability-driven rather than by kind name, so no resource kind
+ * is hardcoded here.
+ *
+ * An unresolvable kind falls back to value level — the honest default, since
+ * `UNDEFINED_KIND` already reports the real problem and guessing type level
+ * would stack a case error on top of it.
+ */
+function levelFor(
+  manifest: ResourceManifest,
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): NameLevel {
+  if (TYPE_LEVEL_DOC_KINDS.has(manifest.kind as string)) return "type";
+  // The root resolver is the right one unconditionally: every manifest
+  // reaching here belongs to a root module, the others having been skipped.
+  const canonical = aliases.resolveKind(manifest.kind as string) ?? (manifest.kind as string);
+  return registry.resolve(canonical)?.capability === "Telo.Type" ? "type" : "value";
+}
+
+/** The noun phrase a diagnostic uses as its subject. */
+function surfaceFor(kind: string): string {
+  switch (kind) {
+    case "Telo.Application":
+    case "Telo.Library":
+      return "module name";
+    case "Telo.Definition":
+    case "Telo.Abstract":
+      return "kind name";
+    case "Telo.Import":
+      return "import alias";
+    default:
+      return "resource name";
+  }
+}
+
+function singular(field: "variables" | "secrets" | "ports"): string {
+  return field === "variables" ? "variable" : field === "secrets" ? "secret" : "port";
+}
+
+function push(
+  out: AnalysisDiagnostic[],
+  violation: NameViolation | undefined,
+  at: { kind: string; name: string; filePath: string | undefined; path: string },
+): void {
+  if (!violation) return;
+  out.push({
+    severity: violation.severity,
+    code: violation.code,
+    source: SOURCE,
+    message: `${at.kind}/${at.name}: ${violation.message}`,
+    data: {
+      resource: { kind: at.kind, name: at.name },
+      filePath: at.filePath,
+      path: at.path,
+    },
+  });
+}

package/src/validate-observed-state.ts

@@ -29,8 +29,15 @@ const SYSTEM_KINDS = new Set([
  * {@link validateObservedStateDeclarations} rather than here, so the author gets
  * a message naming the rule and the fix instead of AJV's "must NOT be valid".
  *
- * Exported from the analyzer and re-used by the kernel's manifest schemas, so
- * the rule has one definition rather than two kept in sync by hand.
+ * THE KERNEL'S SHAPE CHECK, not the analyzer's. The analyzer's builtins point
+ * their `status:` slot at the `JsonSchema7` fragment, which describes the same
+ * block far more precisely; the kernel keeps this permissive one, and the two do
+ * not drift into disagreement because the fragment only ever NARROWS what this
+ * accepts. That split is the same one the `required:` rule above draws: the
+ * loader answers "is this the right shape at all", and the check that can name
+ * the offending keyword and its line stays with `telo check`. Wiring the fragment
+ * into the kernel too would turn a check-time diagnostic into a boot failure for
+ * every already-published manifest carrying a sloppy keyword.
  */
 export const OBSERVED_STATE_SCHEMA = {
   type: "object",

package/src/validate-references.ts

@@ -195,32 +195,11 @@ export function validateReferences(
       });
     }
   }
-  // A resource name must contain no dot. The `!ref` resolver splits the tag's source on
-  // the first dot to separate an import alias from the resource name, so a dotted name
-  // would mis-resolve into a cross-module lookup. This is the load-bearing invariant of
-  // the reference grammar, so it is enforced here rather than left to the (unenforced)
-  // casing convention.
-  for (const [name, list] of byNameAll) {
-    if (!name.includes(".")) continue;
-    for (const r of list) {
-      const m = r.metadata as { source?: string; sourceLine?: number } | undefined;
-      const range =
-        typeof m?.sourceLine === "number"
-          ? {
-              start: { line: m.sourceLine, character: 0 },
-              end: { line: m.sourceLine, character: Number.MAX_SAFE_INTEGER },
-            }
-          : undefined;
-      diagnostics.push({
-        severity: DiagnosticSeverity.Error,
-        code: "INVALID_RESOURCE_NAME",
-        source: SOURCE,
-        message: `${r.kind}/${name}: resource name must not contain '.' — in a '!ref' the '.' separates an import alias from the resource name`,
-        ...(range ? { range } : {}),
-        data: { resource: { kind: r.kind, name }, filePath: m?.source, path: "metadata.name" },
-      });
-    }
-  }
+  // The dot rule that used to live here is now the strictest special case of
+  // the identifier grammar in `validate-identifier-names.ts` — a dot is one of
+  // several characters that make a name unreferenceable, and checking one of
+  // them here while the rest went unchecked is what let a hyphenated name
+  // through to silently evaluate as arithmetic.
 
   // Single-resource map for the resolution / scope lookups below — when a
   // collision exists, falling back to the first occurrence keeps the rest

package/src/validate-requires.ts

@@ -0,0 +1,129 @@
+/**
+ * The strict half of `requires-block.ts` — the accessor/validator split
+ * `zone-slot.ts` / `validate-zone-slots.ts` established, and for the same reason:
+ * the reader must not throw on a malformed block (every consumer would have to
+ * guard), while a malformed block must not pass silently either.
+ *
+ * Two distinct outputs, and conflating them was the whole failure this mechanism
+ * addresses:
+ *
+ *  - **`MODULE_REQUIRES_NEWER_RUNTIME`** — the module is fine and *this runtime*
+ *    is too old. Raised per module before that module's own validation, so the
+ *    version message wins over the vocabulary errors it would otherwise be buried
+ *    in (`ZONE_ANNOTATION_INVALID`, an `additionalProperties` violation against a
+ *    kernel-owned schema, an unknown `use` token). Those errors are true but
+ *    blame the module author for a version skew.
+ *  - **`REQUIRES_INVALID`** — the declaration itself is malformed. Severity turns
+ *    on ownership rather than presence: an ERROR on the entry's own modules,
+ *    whose author can fix it, and a WARNING on a dependency, whose author is the
+ *    only one who can. It is not silent on a dependency, because `readRequires`
+ *    drops an unparseable range and the gate then reads the module as satisfied —
+ *    so it loads while stating a requirement it failed to state, and `telo
+ *    upgrade` (which refuses such a version) would be holding it back for a
+ *    reason the load path never mentions.
+ *
+ * **Unknown axes are suppressed while the `telo` requirement is unmet.** An older
+ * runtime not recognising a newer host axis is a *consequence* of the version
+ * skew — the axis exists, this runtime is simply too old to know it — so
+ * reporting it beside the gate diagnostic would manufacture a second defect from
+ * one cause. Once `telo` is satisfied, an unrecognized axis is a real error: a
+ * runtime at or above the declared generation is expected to know every axis that
+ * generation defines.
+ */
+
+import type { ResourceManifest } from "@telorun/sdk";
+
+import { evaluateRequires, readRequires, type HostVersions } from "./requires-block.js";
+import { TELO_SURFACE_VERSION } from "./telo-version.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+export interface ValidateRequiresOptions {
+  /** The surface generation the analyzing runtime implements. Defaults to this
+   *  build's own — see `AnalysisOptions.teloVersion`. */
+  teloVersion?: string;
+  /** Versions the running host can speak for. Absent in a browser, where there
+   *  is no host to report; supplied by the kernel and CLI. */
+  hostVersions?: HostVersions;
+  /** Module names owned by the entry, when the caller can distinguish them.
+   *  `REQUIRES_INVALID` is limited to these; the gate is not, because a
+   *  dependency this runtime cannot read still stops the consumer dead. */
+  entryModules?: ReadonlySet<string>;
+}
+
+export function validateRequires(
+  manifests: ResourceManifest[],
+  options: ValidateRequiresOptions = {},
+): AnalysisDiagnostic[] {
+  const running = options.teloVersion ?? TELO_SURFACE_VERSION;
+  const out: AnalysisDiagnostic[] = [];
+
+  for (const manifest of manifests) {
+    if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library") continue;
+
+    const doc = manifest as unknown as Record<string, unknown>;
+    const { declared, block, issues } = readRequires(doc);
+    if (!declared) continue;
+
+    const metadata = (manifest.metadata ?? {}) as Record<string, unknown>;
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const filePath = typeof metadata.source === "string" ? metadata.source : undefined;
+    const label = `${manifest.kind}/${name ?? "(unnamed)"}`;
+    const resource = { kind: manifest.kind, name };
+
+    const verdict = evaluateRequires(block, running, options.hostVersions);
+
+    if (!verdict.satisfied) {
+      const axis = verdict.axis === "telo" ? "telo" : `host.${verdict.axis}`;
+      const remedy =
+        verdict.axis === "telo"
+          ? `Upgrade telo, or pin ${name ?? "this module"} to a version whose range accepts ` +
+            `${verdict.running}.`
+          : `Upgrade ${verdict.axis}, or pin ${name ?? "this module"} to a version whose range ` +
+            `accepts ${verdict.running}.`;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "MODULE_REQUIRES_NEWER_RUNTIME",
+        source: SOURCE,
+        message:
+          `${label} requires ${axis} '${verdict.declared.raw}'; this runtime reports ` +
+          `${verdict.running}. ${remedy}`,
+        data: { resource, filePath, path: `requires.${axis}` },
+      });
+    }
+
+    const owned =
+      options.entryModules === undefined ||
+      (typeof metadata.module === "string"
+        ? options.entryModules.has(metadata.module)
+        : name === undefined || options.entryModules.has(name));
+
+    for (const issue of issues) {
+      // See the header: an unknown axis is a symptom while the gate is failing.
+      if (issue.unknownAxis && !verdict.satisfied) continue;
+
+      // A DEPENDENCY's malformed block is not the consumer's to fix, but it must
+      // not be silent either. `readRequires` drops an unparseable range from the
+      // block, so the gate reads it as satisfied and the module loads while
+      // stating a requirement it failed to state — and `telo upgrade`, which
+      // refuses to select such a version, would then be holding a version back
+      // for a reason nothing on the load path ever mentions. A warning is what
+      // makes those two halves agree about the manifest without handing the
+      // consumer an error only its publisher can fix.
+      out.push({
+        severity: owned ? DiagnosticSeverity.Error : DiagnosticSeverity.Warning,
+        code: "REQUIRES_INVALID",
+        source: SOURCE,
+        message: owned
+          ? `${label}: ${issue.message}` + (issue.hint ? ` Write '${issue.hint}' instead.` : "")
+          : `${label}: ${issue.message} Its declared requirement cannot be read, so it is not ` +
+            `enforced here and \`telo upgrade\` will not select this version. Only the module's ` +
+            `publisher can fix it.`,
+        data: { resource, filePath, path: issue.path },
+      });
+    }
+  }
+
+  return out;
+}

package/src/value-type-keyword.ts

@@ -50,6 +50,7 @@ export const ANNOTATION_KEYWORDS = [
   "x-telo-bindings-from",
   "x-telo-catches-for",
   "x-telo-context",
+  "x-telo-context-collection-from",
   "x-telo-context-element-from",
   "x-telo-context-from",
   "x-telo-context-from-ref-kind",

package/src/version-range.ts

@@ -0,0 +1,238 @@
+/**
+ * The version-range grammar `requires:` declares, and the only one Telo reads.
+ *
+ * Built on `module-version-order.ts`'s precedence rather than the `semver`
+ * package, for that file's reason: the analyzer is browser-safe, so the editor
+ * reaches the identical rule the kernel does. A second implementation of "does
+ * this version satisfy this range" would eventually disagree about what a
+ * manifest means, which is the whole failure this mechanism exists to prevent.
+ *
+ * **A range is a CONJUNCTION of explicit comparators** — `>=0.80.0`,
+ * `>=0.40.0 <0.50.0`, `>=0.40.0,<0.50.0`. That is deliberately narrower than
+ * npm's grammar, and every exclusion pays for itself:
+ *
+ *  - **`^` and `~` are rejected**, not reinterpreted. On a `0.x` version both
+ *    mean a single minor (`^0.40.0` is `>=0.40.0 <0.41.0`, identical to
+ *    `~0.40.0`), and Telo ships breaking changes as minor bumps deliberately. So
+ *    the caret reading is *correct* and therefore useless — every module would
+ *    pin to one breaking-change generation and nobody could move telo without
+ *    the whole standard library republishing. It is also the spelling semver
+ *    intuition reaches for first, so accepting it would make the failure both
+ *    common and silent.
+ *  - **A bare version is rejected.** npm reads `0.80.0` as an exact pin, which is
+ *    the same trap in a different costume; reading it as `>=` would contradict
+ *    every other semver consumer. Refusing it and naming the two spellings is
+ *    the only answer that cannot be misread.
+ *  - **`||`, hyphen ranges, `*` and `x` are rejected.** A disjunction has no
+ *    single low or high edge, and the edges are load-bearing: verification runs
+ *    the CLI *at* them, and a declared upper bound must be checked for existence.
+ *    A grammar whose edges are undefined cannot be verified, and an unverifiable
+ *    bound is what this design forbids everywhere else.
+ *
+ * **Prereleases compare by plain precedence**, with no equivalent of npm's rule
+ * that a prerelease only satisfies a range mentioning one at the same
+ * `[major, minor, patch]`. That rule exists to stop a caret range dragging a
+ * consumer onto an `-rc` build; here the version being tested is *the runtime the
+ * user is already running*, not a candidate being selected for them, so the
+ * honest answer is the precedence one — a developer on `0.81.0-rc.1` satisfies
+ * `>=0.80.0` because they genuinely are past it.
+ */
+
+import {
+  compareParsedModuleVersions,
+  parseModuleVersion,
+  type ParsedModuleVersion,
+} from "./module-version-order.js";
+
+/** The comparison a single term applies. */
+export type ComparatorOperator = ">=" | ">" | "<=" | "<";
+
+export interface VersionComparator {
+  operator: ComparatorOperator;
+  /** The version as authored, for diagnostics and for the existence check. */
+  raw: string;
+  parsed: ParsedModuleVersion;
+}
+
+/** A parsed range: every comparator must hold. Never empty. */
+export interface VersionRange {
+  /** The range exactly as authored, quoted verbatim in diagnostics. */
+  raw: string;
+  comparators: VersionComparator[];
+}
+
+/** Why a range string was refused. `hint` is the spelling to use instead, when
+ *  there is an unambiguous one — a rejection that cannot say what to write
+ *  instead is a worse diagnostic than the value it rejects. */
+export interface VersionRangeError {
+  message: string;
+  hint?: string;
+}
+
+export type VersionRangeResult =
+  | { ok: true; range: VersionRange }
+  | { ok: false; error: VersionRangeError };
+
+/** Operators longest-first, so `>=` is matched before `>`. */
+const OPERATORS: ComparatorOperator[] = [">=", "<=", ">", "<"];
+
+function refuse(message: string, hint?: string): VersionRangeResult {
+  return { ok: false, error: hint === undefined ? { message } : { message, hint } };
+}
+
+/**
+ * Refuse with `>=<version>` as the hint — but only when that hint would itself
+ * parse.
+ *
+ * A hint is a repair the author is meant to paste, so one this parser would
+ * reject on the next run is worse than no hint at all: it converts a diagnostic
+ * the author can act on into a loop. Everything unparseable (a two-segment
+ * version, a date, a leftover placeholder) falls back to the message alone,
+ * which still names what is wrong.
+ */
+function hintedRefusal(message: string, version: string): VersionRangeResult {
+  return parseModuleVersion(version) ? refuse(message, `>=${version}`) : refuse(message);
+}
+
+/**
+ * Parse a range, or explain why it cannot be one. Never throws and never
+ * degrades to a permissive reading: a range this refuses is reported, not
+ * silently treated as "no requirement".
+ */
+export function parseVersionRange(raw: unknown): VersionRangeResult {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return refuse(`expected a version range string, got ${describe(raw)}`);
+  }
+  const text = raw.trim();
+
+  if (text.includes("||")) {
+    return refuse(
+      `'${text}' is a disjunction. A range must be a conjunction of comparators, because ` +
+        `verification runs the CLI at its lowest and highest bound and a disjunction has neither`,
+    );
+  }
+  if (/\s-\s/.test(text)) {
+    return refuse(
+      `'${text}' is a hyphen range`,
+      `${text.split(/\s-\s/)[0]?.trim() ?? ""} rewritten as '>=' and '<=' comparators`,
+    );
+  }
+
+  const terms = text.split(/[\s,]+/).filter((t) => t !== "");
+  const comparators: VersionComparator[] = [];
+
+  for (const term of terms) {
+    if (term.startsWith("^") || term.startsWith("~")) {
+      const version = term.slice(1);
+      const parsed = parseModuleVersion(version);
+      const upper =
+        parsed && parsed.major === 0 ? `0.${parsed.minor + 1}.0` : `${(parsed?.major ?? 0) + 1}.0.0`;
+      return refuse(
+        `'${term}' is not accepted. Pre-1.0, '${term[0]}' allows only ${version} up to ` +
+          `${upper}, and Telo ships breaking changes as minor bumps — so it pins this module to ` +
+          `a single release generation, which is almost never what is meant`,
+        `>=${version}`,
+      );
+    }
+    // Any `x`/`*` placeholder, at any position — `*`, `x`, `1.x`, `1.2.x`,
+    // `1.2.*`. Catching only some of them sent the rest to the no-comparator
+    // branch below, which suggested `>=1.2.*` — a hint this very parser rejects,
+    // which is worse than the value it was rejecting.
+    if (/(^|\.)[x*]$/i.test(term) || /(^|\.)[x*]\./i.test(term)) {
+      return refuse(`'${term}' is a wildcard range; write explicit comparators instead`);
+    }
+    if (term.startsWith("=")) {
+      return hintedRefusal(`'${term}' pins one exact version`, term.replace(/^=+/, ""));
+    }
+
+    const operator = OPERATORS.find((op) => term.startsWith(op));
+    if (!operator) {
+      return hintedRefusal(
+        `'${term}' has no comparator. A bare version reads as an exact pin in semver, which is ` +
+          `almost never meant here`,
+        term,
+      );
+    }
+    const version = term.slice(operator.length).trim();
+    const parsed = parseModuleVersion(version);
+    if (!parsed) {
+      return refuse(
+        `'${version}' in '${term}' is not a three-part version (X.Y.Z, optionally -prerelease)`,
+      );
+    }
+    comparators.push({ operator, raw: version, parsed });
+  }
+
+  if (comparators.length === 0) return refuse(`'${text}' declares no comparator`);
+  return { ok: true, range: { raw: text, comparators } };
+}
+
+/** True when `version` satisfies every comparator. An unparseable `version` is
+ *  `false` — never a pass, since the caller is asking whether a real runtime is
+ *  admitted and "cannot tell" must not read as "yes". */
+export function rangeAccepts(range: VersionRange, version: string): boolean {
+  const parsed = parseModuleVersion(version);
+  if (!parsed) return false;
+  return range.comparators.every((c) => {
+    const cmp = compareParsedModuleVersions(parsed, c.parsed);
+    switch (c.operator) {
+      case ">=":
+        return cmp >= 0;
+      case ">":
+        return cmp > 0;
+      case "<=":
+        return cmp <= 0;
+      case "<":
+        return cmp < 0;
+    }
+  });
+}
+
+/** The lower-bound comparator, or `undefined` when the range is open below.
+ *  This is the version verification installs and runs as the low edge. */
+export function lowerBound(range: VersionRange): VersionComparator | undefined {
+  return highest(range.comparators.filter((c) => c.operator === ">=" || c.operator === ">"));
+}
+
+/** The upper-bound comparator, or `undefined` when the range is open above —
+ *  the normal case, where the high edge is HEAD and normal CI already covers it. */
+export function upperBound(range: VersionRange): VersionComparator | undefined {
+  return lowest(range.comparators.filter((c) => c.operator === "<=" || c.operator === "<"));
+}
+
+/** The tightest of several same-direction bounds wins; a range may legitimately
+ *  state more than one, and only the binding bound is an edge worth testing. */
+function highest(list: VersionComparator[]): VersionComparator | undefined {
+  return list.reduce<VersionComparator | undefined>(
+    (best, c) =>
+      best === undefined || compareParsedModuleVersions(c.parsed, best.parsed) > 0 ? c : best,
+    undefined,
+  );
+}
+
+function lowest(list: VersionComparator[]): VersionComparator | undefined {
+  return list.reduce<VersionComparator | undefined>(
+    (best, c) =>
+      best === undefined || compareParsedModuleVersions(c.parsed, best.parsed) < 0 ? c : best,
+    undefined,
+  );
+}
+
+/** True when no version can satisfy the range — `>=0.90.0 <0.80.0`. Reported
+ *  rather than left to fail mysteriously at every consumer. */
+export function isUnsatisfiable(range: VersionRange): boolean {
+  const low = lowerBound(range);
+  const high = upperBound(range);
+  if (!low || !high) return false;
+  const cmp = compareParsedModuleVersions(low.parsed, high.parsed);
+  if (cmp > 0) return true;
+  // `>=X <X` and `>X <=X` admit nothing; `>=X <=X` admits exactly X.
+  if (cmp === 0) return low.operator === ">" || high.operator === "<";
+  return false;
+}
+
+function describe(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}