@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/scala/feature/secrets/plugin/Types.scala

@@ -0,0 +1,110 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Types.scala)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package voxgig.plugin
+
+/** The error type, the sort key, and the handful of helpers every module needs.
+  */
+
+/** Every error carries a section 12 code. Ports compare by CODE and never by
+  * message: wording is a port's own business, and pinning the words would make
+  * every translation a corpus change. The FORMAT, however, is pinned - a
+  * parseable message is what makes a log searchable across twenty languages.
+  *
+  * AN EXCEPTION, NOT AN `Either`. Scala offers both and the canonical raises;
+  * threading a `Left` through `Host.ready` would change the shape of every
+  * call in the port for a difference no corpus entry can see, and would make
+  * this the one port whose control flow does not read like the design.
+  */
+final class PluginError(
+    val code: String,
+    val text: String,
+    val details: Map[String, Value]
+) extends RuntimeException(Types.formatError(code, text, details))
+
+object Types {
+
+  /** Section 5.1's seven statuses, and no more. */
+  val statuses = List(
+    "declared", "loaded", "pending", "live", "failed", "loading", "closing"
+  )
+
+  /** Section 12's detail keys, in the order a message renders them. FIXED, not
+    * the map's: a message is a searchable log line, and a line whose fields
+    * move between runs is not.
+    */
+  val detailOrder = List(
+    "ref", "point", "name", "key", "spec", "refs", "kind", "directive",
+    "cycle", "holders", "cause"
+  )
+
+  /** `plugin/<code>: <text> [<key>=<value> ...]`
+    *
+    * Values render as COMPACT JSON, so a value containing a space or a bracket
+    * cannot break the parse, and a list renders as a JSON array. The bracket is
+    * absent entirely when no field applies.
+    */
+  def formatError(code: String, text: String, details: Map[String, Value]): String = {
+    val parts = detailOrder.filter(details.contains).map(k => k + "=" + details(k).json)
+    val tail = if (parts.isEmpty) "" else parts.mkString(" [", " ", "]")
+    "plugin/" + code + ": " + text + tail
+  }
+
+  /** Throw a section 12 error. One spelling, so every raise site reads the
+    * same. `Nothing` is the return type, so the compiler knows a call is a
+    * terminator and no caller needs a redundant value after one.
+    */
+  def fail(
+      code: String, text: String, details: Map[String, Value] = Map.empty
+  ): Nothing = throw new PluginError(code, text, details)
+
+  /** The section 12 code of an error, or "" for one this library did not throw.
+    * The corpus compares by code, so the driver needs one place that knows how
+    * to read it.
+    */
+  def codeOf(e: Throwable): String = e match {
+    case p: PluginError => p.code
+    case _              => ""
+  }
+
+  def messageOf(e: Throwable): String =
+    Option(e.getMessage).getOrElse(e.toString)
+
+  /** A STABLE sort by a comparable key.
+    *
+    * Scala's `sortBy` IS stable and says so - it is `java.util.Arrays.sort` on
+    * an object array, a TimSort, and `SeqLike.sortBy` documents the guarantee.
+    * Stability is load-bearing: section 7's comparators fall through to a `pos`
+    * or ref tie-break that javascript's stable sort resolves BY POSITION, and a
+    * port that shuffled equal keys would order a teardown differently between
+    * two runs of one process. THE NAME IS WHAT THIS FUNCTION IS FOR: every sort
+    * in the port goes through one place that says stability is required.
+    */
+  def stableSortBy[T](list: List[T])(keyOf: T => List[SortKey]): List[T] =
+    list.sortWith((a, b) => SortKey.compare(keyOf(a), keyOf(b)) < 0)
+}
+
+/** A sort key element. A key is a list of numbers, strings and nested lists,
+  * which is what lets `Capability.rankKey` express "absent version sorts last"
+  * as a leading flag rather than as a comparator.
+  */
+sealed trait SortKey
+final case class KNum(n: Double) extends SortKey
+final case class KText(s: String) extends SortKey
+final case class KList(l: List[SortKey]) extends SortKey
+
+object SortKey {
+
+  def compare(a: List[SortKey], b: List[SortKey]): Int = {
+    val pairs = a.zip(b)
+    pairs.map { case (x, y) => compareOne(x, y) }.find(_ != 0)
+      .getOrElse(a.length.compare(b.length))
+  }
+
+  def compareOne(a: SortKey, b: SortKey): Int = (a, b) match {
+    case (KNum(x), KNum(y))   => x.compare(y)
+    case (KText(x), KText(y)) => x.compare(y)
+    case (KList(x), KList(y)) => compare(x, y)
+    case _                    => 0
+  }
+}

package/project/.sdk/tm/scala/feature/secrets/plugin/Value.scala

@@ -0,0 +1,157 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Value.scala)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package voxgig.plugin
+
+/** The JSON value, and the value model this port holds throughout.
+  *
+  * A `Value` IS A SEALED TRAIT, not `Any`. Scala can express the JSON model
+  * exactly, and `Map[String, Any]` would throw away every guarantee the
+  * language is for - starting with the one that matters most here, that a
+  * pattern match over a sealed hierarchy is CHECKED FOR EXHAUSTIVENESS. Adding
+  * a case to this file makes the compiler name every place that has to handle
+  * it, which is a stronger discipline than any of the untyped ports can have.
+  *
+  * `VNum` is a `Double` because JSON HAS ONE NUMBER TYPE. The canonical is
+  * javascript, `1` and `1.0` are the same value there, and a port that split
+  * them would disagree with the corpus on which of two spellings a document
+  * used.
+  *
+  * NO JSON LIBRARY, AND NO `libraryDependencies` (section 16). The library is
+  * allowed exactly one runtime dependency, `voxgig/struct`, which has no scala
+  * port; everything else is the standard library.
+  */
+sealed trait Value {
+
+  /** The value at a key, or None. `None` is ABSENT; `Some(VNull)` is a present
+    * null, and that is the whole reason this returns an `Option` rather than
+    * `VNull` for both.
+    */
+  def get(key: String): Option[Value] = this match {
+    case VMap(entries) => entries.get(key)
+    case _             => None
+  }
+
+  /** PRESENCE, which is what distinguishes an authored null from absence. */
+  def has(key: String): Boolean = get(key).isDefined
+
+  /** The value at a key with an absent key flattened to `VNull` - for the many
+    * sites that treat the two alike.
+    */
+  def at(key: String): Value = get(key).getOrElse(VNull)
+
+  /** The keys of a map, SORTED - every walk of a map goes through here. A scala
+    * `Map` past four entries is a `HashMap` and iterates in hash order, so this
+    * is not tidiness: without it a teardown order changes between two runs of
+    * the same process.
+    */
+  def keys: List[String] = this match {
+    case VMap(entries) => entries.keys.toList.sorted
+    case _             => Nil
+  }
+
+  def items: List[Value] = this match {
+    case VList(l) => l
+    case _        => Nil
+  }
+
+  def entries: Map[String, Value] = this match {
+    case VMap(m) => m
+    case _       => Map.empty
+  }
+
+  def isNull: Boolean = this == VNull
+
+  def isMap: Boolean = this.isInstanceOf[VMap]
+
+  def isList: Boolean = this.isInstanceOf[VList]
+
+  def asString: Option[String] = this match {
+    case VStr(s) => Some(s)
+    case _       => None
+  }
+
+  def asDouble: Option[Double] = this match {
+    case VNum(n) => Some(n)
+    case _       => None
+  }
+
+  /** An INTEGER, and only when the value is one. Section 7's band is an integer
+    * the document wrote as one, and every number here is a `Double`, so the
+    * test is "a whole double" - `VBool(true)` and `VStr("2")` are different
+    * cases and reach neither branch.
+    */
+  def asInt: Option[Int] = this match {
+    case VNum(n) if n == math.floor(n) && !n.isInfinite => Some(n.toInt)
+    case _                                              => None
+  }
+
+  /** JSON truthiness: null and false, and nothing else, are false. Scala has no
+    * truthiness of its own - `if (0)` does not compile - so this is where the
+    * model's rule is written down.
+    */
+  def truthy: Boolean = this match {
+    case VNull    => false
+    case VBool(b) => b
+    case _        => true
+  }
+
+  /** Set a key, returning the new value. A `Value` is immutable, so every
+    * mutation is explicit and nothing aliases.
+    */
+  def setting(key: String, value: Value): Value = VMap(entries + (key -> value))
+
+  /** COMPACT JSON, map keys in sorted order. A whole double renders WITHOUT its
+    * fraction, so `1.0` and `1` spell the same - the corpus writes both and a
+    * message quoting one must not depend on which.
+    */
+  def json: String = this match {
+    case VNull    => "null"
+    case VBool(b) => if (b) "true" else "false"
+    case VNum(n) =>
+      if (n == math.floor(n) && !n.isInfinite) n.toLong.toString else n.toString
+    case VStr(s)  => Value.quote(s)
+    case VList(l) => l.map(_.json).mkString("[", ",", "]")
+    case VMap(_) =>
+      keys.map(k => Value.quote(k) + ":" + at(k).json).mkString("{", ",", "}")
+    // Anything the model has no JSON spelling for - a host, an instance
+    // handle, a callback the driver exported.
+    case VOpaque(_) => "\"(opaque)\""
+  }
+}
+
+case object VNull extends Value
+final case class VBool(b: Boolean) extends Value
+final case class VNum(n: Double) extends Value
+final case class VStr(s: String) extends Value
+final case class VList(l: List[Value]) extends Value
+final case class VMap(m: Map[String, Value]) extends Value
+
+/** A host object published through `exports` (section 11). The design lets a
+  * plugin export "a client" - a thing the library never inspects - and in a
+  * statically typed port that needs an escape hatch. It is never produced by
+  * the parser and never compared as data: `AnyRef` equality is reference
+  * equality unless the object overrides it, which no instance handle does.
+  */
+final case class VOpaque(obj: AnyRef) extends Value
+
+object Value {
+
+  def map(pairs: (String, Value)*): Value = VMap(pairs.toMap)
+
+  def list(items: Value*): Value = VList(items.toList)
+
+  def quote(s: String): String = {
+    val out = new StringBuilder("\"")
+    s.foreach {
+      case '"'                    => out.append("\\\"")
+      case '\\'                   => out.append("\\\\")
+      case '\n'                   => out.append("\\n")
+      case '\r'                   => out.append("\\r")
+      case '\t'                   => out.append("\\t")
+      case c if c < ' '           => out.append("\\u%04x".format(c.toInt))
+      case c                      => out.append(c)
+    }
+    out.append('"').toString
+  }
+}

package/project/.sdk/tm/scala/feature/secrets/plugin/Version.scala

@@ -0,0 +1,136 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Version.scala)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package voxgig.plugin
+
+/** Versions and ranges (section 11.2).
+  *
+  * TWO FIELDS AND ONE PREDICATE. A capability declares `version`, a concrete
+  * version. A requirement declares `range`. A requirement is satisfied when the
+  * names match, the `match` passes, and the provider's `version` falls inside
+  * the requirement's `range`.
+  *
+  * That is the whole rule. There is no third field and no second comparison -
+  * an earlier draft added a provider-side `compat` range, which left three
+  * values and no statement of how they combine, and three defensible readings
+  * of one declaration is worse than the ambiguity it was introduced to fix.
+  */
+object Version {
+
+  /** A COMPONENT IS BOUNDED, and the bound is the model's, not the host
+    * language's. A scala `Long` is 64-bit and javascript stops being exact past
+    * 2**53, so `9223372036854775808.0.0` parsed to an exact value here and a
+    * rounded one there. 2**31-1 is the smallest bound every target language
+    * holds exactly, which makes it the model's.
+    */
+  val componentMax: Double = 2147483647.0
+
+  /** The three dot-separated numeric parts, or None - written as a scan for the
+    * same reason `Refs` is: no regex, and nothing to get wrong about anchoring.
+    */
+  def scan(s: String): Option[List[String]] = {
+    val parts = s.split("\\.", -1).toList
+    if (parts.length <= 3 && parts.forall(p => p.nonEmpty && p.forall(_.isDigit))) {
+      Some(parts)
+    } else {
+      None
+    }
+  }
+
+  /** A component parses as a `Double` so that `major + 1` at `componentMax` is
+    * 2147483648 rather than an overflow, and so that every number in this port
+    * is one type. `BigInt` first, because a forty-digit component read straight
+    * into a `Long` would wrap past the check meant to reject it.
+    */
+  def component(digits: String, whole: String, field: String): Double = {
+    val value = BigInt(digits)
+    if (BigInt(componentMax.toLong) < value) {
+      Types.fail(
+        "plugin_bad_range",
+        "version component out of range in " + whole + ": " + digits,
+        Map(field -> VStr(whole))
+      )
+    }
+    value.toDouble
+  }
+
+  /** Two forms and no more (section 11.2):
+    *
+    *   '2.1'    >= 2.1.0 and < 3.0.0
+    *   '~2.1'   >= 2.1.0 and < 2.2.0
+    */
+  def parseRange(range: Value): Value = {
+    val s = range.asString.getOrElse(
+      Types.fail(
+        "plugin_bad_range", "invalid range: " + Refs.show(range), Map("range" -> range)
+      )
+    )
+    if (s.isEmpty) {
+      Types.fail("plugin_bad_range", "invalid range: " + s, Map("range" -> range))
+    }
+    val tilde = s.startsWith("~")
+    val body = if (tilde) s.substring(1) else s
+    val parts = scan(body).getOrElse(
+      Types.fail("plugin_bad_range", "invalid range: " + s, Map("range" -> range))
+    )
+    val major = component(parts.head, s, "range")
+    val minor = if (parts.length > 1) component(parts(1), s, "range") else 0.0
+    val patch = if (parts.length > 2) component(parts(2), s, "range") else 0.0
+
+    Value.map(
+      "lo" -> Value.list(VNum(major), VNum(minor), VNum(patch)),
+      "hi" -> (if (tilde) Value.list(VNum(major), VNum(minor + 1), VNum(0))
+               else Value.list(VNum(major + 1), VNum(0), VNum(0)))
+    )
+  }
+
+  def parseVersion(version: Value): List[Double] = {
+    val s = version.asString.getOrElse(
+      Types.fail(
+        "plugin_bad_range", "invalid version: " + Refs.show(version),
+        Map("version" -> version)
+      )
+    )
+    val parts = scan(s).getOrElse(
+      Types.fail(
+        "plugin_bad_range", "invalid version: " + s, Map("version" -> version)
+      )
+    )
+    List(
+      component(parts.head, s, "version"),
+      if (parts.length > 1) component(parts(1), s, "version") else 0.0,
+      if (parts.length > 2) component(parts(2), s, "version") else 0.0
+    )
+  }
+
+  def versionCmp(a: List[Double], b: List[Double]): Int = {
+    val diffs = (0 until 3).map { i =>
+      val x = if (i < a.length) a(i) else 0.0
+      val y = if (i < b.length) b(i) else 0.0
+      x.compare(y)
+    }
+    diffs.find(_ != 0).getOrElse(0)
+  }
+
+  /** The one satisfaction predicate: lo <= version < hi. */
+  def satisfies(version: Value, range: Value): Boolean = {
+    val v = parseVersion(version)
+    val r = parseRange(range)
+    val lo = r.at("lo").items.flatMap(_.asDouble)
+    val hi = r.at("hi").items.flatMap(_.asDouble)
+    versionCmp(v, lo) >= 0 && versionCmp(v, hi) < 0
+  }
+
+  /** `satisfies` for the internal callers that treat an unparseable version or
+    * range as "does not satisfy" - Capability and Graph, both of which run over
+    * data the corpus has already admitted.
+    */
+  def satisfiesq(version: Value, range: Value): Boolean =
+    try satisfies(version, range)
+    catch { case _: PluginError => false }
+
+  /** The numeric parts of a version, or zeros - a SORT KEY, never a check. */
+  def versionParts(text: Value): List[Double] =
+    try parseVersion(text)
+    catch { case _: PluginError => List(0.0, 0.0, 0.0) }
+}