@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Refs.kt

@@ -0,0 +1,125 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Refs.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * Identity: name+tag, written `name$tag` (section 4).
+ *
+ * The four pure functions, and the whole of what `ref` pins. They are the
+ * first thing a new port implements and the first corpus section it passes.
+ */
+object Refs {
+
+    /**
+     * Section 4: `[a-zA-Z@][a-zA-Z0-9.~_\-/]*`, max 1024.
+     *
+     * NO `^` AND NO `$`, because `Regex.matches` requires the WHOLE input to
+     * match - it is `Matcher.matches`, not `find`. Writing the anchors would
+     * be harmless and misleading: it would suggest they are what rejects
+     * `"abc\n"`, and they are not. Reaching for `containsMatchIn` here is
+     * what would admit a ref grammar with a newline in it, and
+     * `ref/name#trailing-newline` says so.
+     */
+    private val NAME_RE = Regex("[a-zA-Z@][a-zA-Z0-9.~_\\-/]*")
+
+    /**
+     * Section 4: `[a-zA-Z0-9.~_-]+`, max 1024, or empty.
+     *
+     * The asymmetry with a name is deliberate: a tag MAY start with a digit
+     * because auto-tagging assigns integer tags (`stripe$1`), and a tag
+     * admits neither `@` nor `/` because a name is a package specifier and a
+     * tag is not.
+     */
+    private val TAG_RE = Regex("[a-zA-Z0-9.~_-]+")
+
+    private const val REF_MAX = 1024
+
+    fun checkName(name: Any?): Boolean =
+        name is String && "" != name && name.length <= REF_MAX &&
+            NAME_RE.matches(name)
+
+    fun checkTag(tag: Any?): Boolean {
+        if (tag !is String) return false
+        // The empty tag is an ordinary tag (section 4 rule 2). The
+        // single-instance case writes no tag and never learns tags exist.
+        if ("" == tag) return true
+        return tag.length <= REF_MAX && TAG_RE.matches(tag)
+    }
+
+    /**
+     * `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both
+     * give tag "".
+     */
+    fun parseRef(str: Any?): Map<String, Any?> {
+        if (str !is String) Types.fail("plugin_bad_name", "ref must be a string")
+        // Split on the FIRST `$`. Nothing in the grammar decides this - `$`
+        // is in neither character class - so the corpus is the arbiter
+        // (section 4 rule 5), and it picks the split that blames the part
+        // actually at fault: `a$b$c` is a good name with a bad tag, not the
+        // reverse.
+        val cut = str.indexOf('$')
+        val name = if (0 > cut) str else str.substring(0, cut)
+        val tag = if (0 > cut) "" else str.substring(cut + 1)
+
+        if (!checkName(name)) {
+            Types.fail("plugin_bad_name", "invalid plugin name: $name", mapOf("name" to name))
+        }
+        if (!checkTag(tag)) {
+            Types.fail(
+                "plugin_bad_tag", "invalid plugin tag: $tag",
+                mapOf("name" to name, "tag" to tag)
+            )
+        }
+        val out = java.util.TreeMap<String, Any?>()
+        out["name"] = name
+        out["tag"] = tag
+        return out
+    }
+
+    /**
+     * The pair -> `name$tag`. An empty tag NEVER writes the separator, which
+     * is the half of canonicalization `formatRef` owns: parse tolerates
+     * `stripe$`, format never produces it, so a round trip is idempotent.
+     */
+    @JvmOverloads
+    fun formatRef(name: Any?, tag: Any? = null): String {
+        val t = tag ?: ""
+        if (!checkName(name)) {
+            Types.fail("plugin_bad_name", "invalid plugin name: $name", mapOf("name" to name))
+        }
+        if (!checkTag(t)) {
+            Types.fail(
+                "plugin_bad_tag", "invalid plugin tag: $t",
+                mapOf("name" to name, "tag" to t)
+            )
+        }
+        return if ("" == t) name as String else "$name\$$t"
+    }
+
+    /**
+     * The canonical spelling of a ref. Section 4 rule 5: ports must
+     * canonicalize before comparison.
+     */
+    fun canonRef(str: Any?): String {
+        val r = parseRef(str)
+        return formatRef(r["name"], r["tag"])
+    }
+
+    /**
+     * `canonRef` for the internal callers that want the input back unchanged
+     * when it is not well formed. NEVER use it where a bad ref must be
+     * reported - the corpus pins plugin_bad_name at every public entry.
+     */
+    fun canon(str: Any?): String = try {
+        canonRef(str)
+    } catch (e: PluginError) {
+        str as String
+    }
+
+    fun refName(str: Any?): String = try {
+        parseRef(str)["name"] as String
+    } catch (e: PluginError) {
+        str as String
+    }
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Resolve.kt

@@ -0,0 +1,66 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Resolve.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * Dynamic resolution (section 10.2) - name to candidate module ids.
+ *
+ * PURE. It returns the ids a host WOULD try, in order; it does not load
+ * anything. That separation is what lets the corpus pin resolution in every
+ * language including those with no dynamic loading at all, and it is why
+ * section 15.4 puts real module loading in per-port integration tests rather
+ * than here.
+ */
+object Resolve {
+
+    val defaultSources: List<Any?> = listOf(
+        mapOf(
+            "kind" to "module",
+            "prefix" to listOf("@voxgig/plugin-", "voxgig-plugin-", "plugin-", "")
+        )
+    )
+
+    @JvmOverloads
+    fun resolveCandidates(name: String, sources: Any? = null): List<String> {
+        // A SCOPED NAME RESOLVES VERBATIM ONLY (section 10.2). `@acme/thing`
+        // is already a package id; prefixing it produces
+        // `@voxgig/plugin-@acme/thing`, which is not a thing that can exist.
+        if (name.startsWith("@")) return listOf(name)
+
+        val list = if (sources is List<*> && sources.isNotEmpty()) sources else defaultSources
+        val out = ArrayList<String>()
+
+        for (src in list) {
+            when (Types.get(src, "kind")) {
+                "module" -> {
+                    val declared = Types.get(src, "prefix")
+                    val prefixes = if (declared is List<*> && declared.isNotEmpty()) {
+                        declared
+                    } else {
+                        listOf("")
+                    }
+                    for (p in prefixes) {
+                        val id = "$p$name"
+                        if (!out.contains(id)) out.add(id)
+                    }
+                }
+                "path" -> {
+                    val dir = (Types.get(src, "dir") as String).trimEnd('/')
+                    val id = "$dir/$name"
+                    if (!out.contains(id)) out.add(id)
+                }
+            }
+        }
+        return out
+    }
+
+    /**
+     * A MODULE PATH IS NOT A NAME (section 10.2). The ref grammar starts a
+     * name with a letter or `@`, so `./local/thing` is not a ref and never
+     * reaches candidate generation - seneca allows a path where a plugin name
+     * goes, and this design deliberately does not, because a ref is an
+     * ADDRESS WITHIN A HOST and a path is a LOCATION ON A DISK.
+     */
+    fun resolveFrom(from: Any?): List<Any?> = listOf(from)
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Types.kt

@@ -0,0 +1,171 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Types.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * The value model, the error type, and the JSON writer.
+ *
+ * THE VALUE MODEL IS `Any?`, and each JSON type has ONE kotlin spelling:
+ * `null`, [Boolean], [Double], [String], `List<Any?>`, `Map<String, Any?>`.
+ * A map is always a [java.util.TreeMap] - every port has to sort its keys
+ * before iterating, and a sorted map makes that the default rather than a
+ * discipline to remember.
+ *
+ * A NUMBER IS ALWAYS A `Double`, because JSON has one number type and the
+ * canonical is javascript. A `Long` anywhere in this data would compare
+ * unequal to the `Double` the parser produced for the same literal -
+ * `1L == 1.0` is false for `Any?` in kotlin, exactly as
+ * `Integer.valueOf(1).equals(Double.valueOf(1))` is in java - and the
+ * corpus would fail on a distinction the model does not have.
+ */
+object Types {
+
+    /** Section 5.1's seven statuses, and no more. */
+    val statuses = listOf(
+        "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 = listOf(
+        "ref", "point", "name", "key", "spec", "refs", "kind", "directive",
+        "cycle", "holders", "cause"
+    )
+
+    /** The value at a key, or null. Absence and null read the same here. */
+    fun get(m: Any?, k: String): Any? = if (m is Map<*, *>) m[k] else null
+
+    /** PRESENCE, which is what distinguishes an authored null from absence. */
+    fun has(m: Any?, k: String): Boolean = m is Map<*, *> && m.containsKey(k)
+
+    /**
+     * The keys of a map, SORTED - every walk of a map goes through here. A
+     * `TreeMap` is already in this order, and this is what says so at the
+     * call site rather than relying on the caller knowing the type.
+     */
+    fun keys(m: Any?): List<String> =
+        if (m is Map<*, *>) m.keys.map { it as String }.sorted() else emptyList()
+
+    /**
+     * JSON truthiness: null and false, and nothing else, are false. Kotlin
+     * has no truthiness of its own - `if (0)` does not compile - so this is
+     * where the model's rule is written down.
+     */
+    fun truthy(v: Any?): Boolean = !(null == v || false == v)
+
+    /**
+     * 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" - `true` and `"2"` are not
+     * bands and neither reaches this.
+     */
+    fun asInt(v: Any?): Int? = when {
+        v is Double && v == Math.floor(v) && !v.isInfinite() -> v.toInt()
+        v is Int -> v
+        else -> null
+    }
+
+    /**
+     * A STABLE sort by a comparable key.
+     *
+     * Kotlin's `sortedWith` delegates to `java.util.Arrays.sort` on an
+     * object array, which is a TimSort and documented stable. 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 kept so that one place
+     * in the port says so.
+     */
+    fun <T> stableSortBy(list: List<T>, keyOf: (T) -> List<Any>): List<T> =
+        // `Comparator { }` and not a bare lambda: SAM conversion for a
+        // KOTLIN functional interface arrived in 1.4, and this port targets
+        // the 1.3 compiler. `java.util.Comparator` converts in every version.
+        list.sortedWith(Comparator { a: T, b: T -> compareKeys(keyOf(a), keyOf(b)) })
+
+    /**
+     * Compare two sort keys element by element. A key is a list of numbers,
+     * strings and nested lists, which is what lets `rankKey` express "absent
+     * version sorts last" as a leading flag rather than as a comparator.
+     */
+    @Suppress("UNCHECKED_CAST")
+    fun compareKeys(a: List<Any>, b: List<Any>): Int {
+        for (i in 0 until minOf(a.size, b.size)) {
+            val x = a[i]
+            val y = b[i]
+            val c = if (x is List<*> && y is List<*>) {
+                compareKeys(x as List<Any>, y as List<Any>)
+            } else {
+                (x as Comparable<Any>).compareTo(y)
+            }
+            if (0 != c) return c
+        }
+        return a.size.compareTo(b.size)
+    }
+
+    /**
+     * JSON equality: same type, then same value.
+     *
+     * `true == 1` is false in kotlin for `Any?`, so the bool guard the
+     * dynamic ports need is not required here. Every number is a `Double`,
+     * so the `1` versus `1.0` question the model does not have never arises.
+     */
+    fun same(a: Any?, b: Any?): Boolean {
+        if (a is Map<*, *> && b is Map<*, *>) {
+            if (a.size != b.size) return false
+            return a.all { (k, v) -> b.containsKey(k) && same(v, b[k]) }
+        }
+        if (a is List<*> || b is List<*>) {
+            if (a !is List<*> || b !is List<*> || a.size != b.size) return false
+            return a.indices.all { same(a[it], b[it]) }
+        }
+        if (a is Map<*, *> || b is Map<*, *>) return false
+        return a == b
+    }
+
+    /**
+     * `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.
+     */
+    fun formatError(code: String, text: String, details: Map<String, Any?>): String {
+        val parts = detailOrder.filter { details.containsKey(it) }
+            .map { "$it=${Json.write(details[it])}" }
+        val tail = if (parts.isEmpty()) "" else " [${parts.joinToString(" ")}]"
+        return "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 `return` after one.
+     */
+    fun fail(code: String, text: String, details: Map<String, Any?> = emptyMap()): Nothing =
+        throw 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.
+     */
+    fun codeOf(e: Throwable): String = if (e is PluginError) e.code else ""
+
+    fun messageOf(e: Throwable): String = e.message ?: e.toString()
+}
+
+/**
+ * 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.
+ */
+class PluginError(
+    val code: String,
+    val text: String,
+    val details: Map<String, Any?>
+) : RuntimeException(Types.formatError(code, text, details))

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Version.kt

@@ -0,0 +1,132 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Version.kt)
+// 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 KOTLINPACKAGE.feature.secrets.plugin
+
+import java.math.BigInteger
+
+/**
+ * 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 {
+
+    private val VERSION_RE = Regex("(\\d+)(?:\\.(\\d+))?(?:\\.(\\d+))?")
+
+    /**
+     * A COMPONENT IS BOUNDED, and the bound is the model's, not the host
+     * language's. A kotlin `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.
+     */
+    const val COMPONENT_MAX = 2147483647
+
+    /**
+     * `BigInteger`, not `toInt()`: a component of forty digits overflows
+     * silently, and the check below would then pass for a value plainly out
+     * of range.
+     */
+    private fun component(digits: String, whole: String, field: String): Double {
+        val value = BigInteger(digits)
+        if (BigInteger.valueOf(COMPONENT_MAX.toLong()) < value) {
+            Types.fail(
+                "plugin_bad_range",
+                "version component out of range in $whole: $digits",
+                mapOf(field to whole)
+            )
+        }
+        return 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
+     */
+    fun parseRange(range: Any?): Map<String, Any?> {
+        if (range !is String || "" == range) {
+            Types.fail("plugin_bad_range", "invalid range: $range", mapOf("range" to range))
+        }
+        val tilde = range.startsWith("~")
+        val body = if (tilde) range.substring(1) else range
+        val m = VERSION_RE.matchEntire(body)
+            ?: Types.fail("plugin_bad_range", "invalid range: $range", mapOf("range" to range))
+
+        val major = component(m.groupValues[1], range, "range")
+        val minor = if ("" == m.groupValues[2]) 0.0 else component(m.groupValues[2], range, "range")
+        val patch = if ("" == m.groupValues[3]) 0.0 else component(m.groupValues[3], range, "range")
+
+        val out = java.util.TreeMap<String, Any?>()
+        out["lo"] = listOf(major, minor, patch)
+        // `major + 1` on a COMPONENT_MAX major is 2147483648, which an `Int`
+        // cannot hold - it wraps to the negative bound, and
+        // `version/range#component-max` is the entry that says so. Every number
+        // in this port is a `Double` for the model's reason; here it is also
+        // the arithmetic's.
+        out["hi"] = if (tilde) listOf(major, minor + 1, 0.0) else listOf(major + 1, 0.0, 0.0)
+        return out
+    }
+
+    fun parseVersion(version: Any?): List<Double> {
+        if (version !is String) {
+            Types.fail("plugin_bad_range", "invalid version: $version", mapOf("version" to version))
+        }
+        val m = VERSION_RE.matchEntire(version)
+            ?: Types.fail(
+                "plugin_bad_range", "invalid version: $version",
+                mapOf("version" to version)
+            )
+        return listOf(
+            component(m.groupValues[1], version, "version"),
+            if ("" == m.groupValues[2]) 0.0 else component(m.groupValues[2], version, "version"),
+            if ("" == m.groupValues[3]) 0.0 else component(m.groupValues[3], version, "version")
+        )
+    }
+
+    fun versionCmp(a: List<Double>, b: List<Double>): Int {
+        for (i in 0 until 3) {
+            val x = if (i < a.size) a[i] else 0.0
+            val y = if (i < b.size) b[i] else 0.0
+            if (x != y) return if (x < y) -1 else 1
+        }
+        return 0
+    }
+
+    /** The one satisfaction predicate: lo <= version < hi. */
+    fun satisfies(version: Any?, range: Any?): Boolean {
+        val v = parseVersion(version)
+        val r = parseRange(range)
+        @Suppress("UNCHECKED_CAST")
+        return 0 <= versionCmp(v, r["lo"] as List<Double>) &&
+            0 > versionCmp(v, r["hi"] as List<Double>)
+    }
+
+    /**
+     * `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.
+     */
+    fun satisfiesq(version: Any?, range: Any?): Boolean = try {
+        satisfies(version, range)
+    } catch (e: PluginError) {
+        false
+    }
+
+    /** The numeric parts of a version, or zeros - a SORT KEY, never a check. */
+    fun versionParts(text: String): List<Double> = try {
+        parseVersion(text)
+    } catch (e: PluginError) {
+        listOf(0.0, 0.0, 0.0)
+    }
+}