@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/csharp/feature/secrets/plugin/Refs.cs

@@ -0,0 +1,198 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (csharp/src/Refs.cs)
+// 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.
+using System;
+using System.Collections.Generic;
+
+namespace Voxgig.Plugin
+{
+    /// <summary>
+    /// Identity: name+tag, written <c>name$tag</c> (§4).
+    ///
+    /// <para>The four pure functions, and the whole of what <c>ref</c>
+    /// pins. They are the first thing a new port implements and the first
+    /// corpus section it passes.</para>
+    ///
+    /// <para>NO REGEX. <c>System.Text.RegularExpressions</c>' <c>$</c>
+    /// matches before a final <c>\n</c>, so a <c>^...$</c> spelling would
+    /// admit <c>"stripe\n"</c> as a name - the hole the ruby port surfaced
+    /// in python. A character-class walk cannot have it, and the four
+    /// <c>#trailing-newline</c> entries pass here without the port having
+    /// to know they exist.</para>
+    /// </summary>
+    public static class Refs
+    {
+        public const int REF_MAX = 1024;
+
+        /// §4: <c>^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$</c>, max 1024.
+        public static bool CheckName(object name)
+        {
+            var text = Types.Str(name);
+            if (null == text || 0 == text.Length || REF_MAX < text.Length)
+            {
+                return false;
+            }
+            var first = text[0];
+            if (!IsAlpha(first) && '@' != first)
+            {
+                return false;
+            }
+            for (var i = 1; i < text.Length; i++)
+            {
+                var c = text[i];
+                if (!IsAlpha(c) && !IsDigit(c)
+                    && '.' != c && '~' != c && '_' != c && '-' != c && '/' != c)
+                {
+                    return false;
+                }
+            }
+            return true;
+        }
+
+        /// <summary>
+        /// §4: <c>^[a-zA-Z0-9.~_-]+$</c>, max 1024, or empty.
+        ///
+        /// <para>The asymmetry with a name is deliberate: a tag MAY start
+        /// with a digit because auto-tagging assigns integer tags
+        /// (<c>stripe$1</c>), and a tag admits neither <c>@</c> nor
+        /// <c>/</c> because a name is a package specifier and a tag is
+        /// not.</para>
+        /// </summary>
+        public static bool CheckTag(object tag)
+        {
+            var text = Types.Str(tag);
+            if (null == text)
+            {
+                return false;
+            }
+            // The empty tag is an ordinary tag (§4 rule 2). The
+            // single-instance case writes no tag and never learns tags
+            // exist.
+            if (0 == text.Length)
+            {
+                return true;
+            }
+            if (REF_MAX < text.Length)
+            {
+                return false;
+            }
+            foreach (var c in text)
+            {
+                if (!IsAlpha(c) && !IsDigit(c) && '.' != c && '~' != c && '_' != c && '-' != c)
+                {
+                    return false;
+                }
+            }
+            return true;
+        }
+
+        private static bool IsAlpha(char c)
+        {
+            return ('a' <= c && c <= 'z') || ('A' <= c && c <= 'Z');
+        }
+
+        private static bool IsDigit(char c)
+        {
+            return '0' <= c && c <= '9';
+        }
+
+        /// <summary>
+        /// <c>name$tag</c> -&gt; the pair. Canonicalizing: <c>stripe$</c>
+        /// and <c>stripe</c> both give tag "".
+        /// </summary>
+        public static SortedDictionary<string, object> ParseRef(object value)
+        {
+            var text = Types.Str(value);
+            if (null == text)
+            {
+                Types.Fail("plugin_bad_name", "ref must be a string", null);
+            }
+
+            // Split on the FIRST `$`. Nothing in the grammar decides this -
+            // `$` is in neither character class - so the corpus is the
+            // arbiter (§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.
+            var cut = text.IndexOf('$');
+            var name = cut < 0 ? text : text.Substring(0, cut);
+            var tag = cut < 0 ? "" : text.Substring(cut + 1);
+
+            if (!CheckName(name))
+            {
+                Types.Fail("plugin_bad_name", "invalid plugin name: " + name,
+                           Types.Details("name", name));
+            }
+            if (!CheckTag(tag))
+            {
+                Types.Fail("plugin_bad_tag", "invalid plugin tag: " + tag,
+                           Types.Details("name", name, "tag", tag));
+            }
+
+            var out_ = Types.NewMap();
+            out_["name"] = name;
+            out_["tag"] = tag;
+            return out_;
+        }
+
+        /// <summary>
+        /// The pair -&gt; <c>name$tag</c>. An empty tag NEVER writes the
+        /// separator, which is the half of canonicalization this owns:
+        /// parse tolerates <c>stripe$</c>, format never produces it, so a
+        /// round trip is idempotent.
+        /// </summary>
+        public static string FormatRef(object name, object tag)
+        {
+            var usetag = null == tag ? "" : tag;
+            if (!CheckName(name))
+            {
+                Types.Fail("plugin_bad_name", "invalid plugin name: " + Json.Write(name),
+                           Types.Details("name", name));
+            }
+            if (!CheckTag(usetag))
+            {
+                Types.Fail("plugin_bad_tag", "invalid plugin tag: " + Json.Write(usetag),
+                           Types.Details("name", name, "tag", usetag));
+            }
+            var text = Types.Str(usetag);
+            return 0 == text.Length ? Types.Str(name) : Types.Str(name) + "$" + text;
+        }
+
+        /// The canonical spelling of a ref. §4 rule 5: ports must
+        /// canonicalize before comparison.
+        public static string CanonRef(object value)
+        {
+            var parsed = ParseRef(value);
+            return FormatRef(parsed["name"], parsed["tag"]);
+        }
+
+        /// <summary>
+        /// 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.
+        /// </summary>
+        public static string Canon(string text)
+        {
+            try
+            {
+                return CanonRef(text);
+            }
+            catch (PluginException)
+            {
+                return text;
+            }
+        }
+
+        public static string RefName(string text)
+        {
+            try
+            {
+                return Types.Str(ParseRef(text)["name"]);
+            }
+            catch (PluginException)
+            {
+                return text;
+            }
+        }
+    }
+}

package/project/.sdk/tm/csharp/feature/secrets/plugin/Resolve.cs

@@ -0,0 +1,95 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (csharp/src/Resolve.cs)
+// 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.
+using System;
+using System.Collections.Generic;
+
+namespace Voxgig.Plugin
+{
+    /// <summary>
+    /// Dynamic resolution (§10.2) - name to candidate module ids.
+    ///
+    /// <para>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 §15.4 puts real module loading in
+    /// per-port integration tests rather than here.</para>
+    /// </summary>
+    public static class Resolve
+    {
+        public static List<object> DefaultSources()
+        {
+            var src = Types.NewMap();
+            src["kind"] = "module";
+            src["prefix"] = new List<object>
+            {
+                "@voxgig/plugin-", "voxgig-plugin-", "plugin-", "",
+            };
+            return new List<object> { src };
+        }
+
+        public static List<object> ResolveCandidates(string name, object sources)
+        {
+            var out_ = new List<object>();
+
+            // A SCOPED NAME RESOLVES VERBATIM ONLY (§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("@", StringComparison.Ordinal))
+            {
+                out_.Add(name);
+                return out_;
+            }
+
+            var given = Types.List(sources);
+            var list = (null == given || 0 == given.Count) ? DefaultSources() : given;
+
+            foreach (var src in list)
+            {
+                var kind = Types.Str(Types.Get(src, "kind"));
+                if ("module" == kind)
+                {
+                    var prefixes = Types.List(Types.Get(src, "prefix"));
+                    if (null == prefixes || 0 == prefixes.Count)
+                    {
+                        prefixes = new List<object> { "" };
+                    }
+                    foreach (var p in prefixes)
+                    {
+                        var id = Types.Str(p) + name;
+                        if (!out_.Contains(id))
+                        {
+                            out_.Add(id);
+                        }
+                    }
+                }
+                else if ("path" == kind)
+                {
+                    var dir = Types.Str(Types.Get(src, "dir")) ?? "";
+                    dir = dir.TrimEnd('/');
+                    var id = dir + "/" + name;
+                    if (!out_.Contains(id))
+                    {
+                        out_.Add(id);
+                    }
+                }
+            }
+
+            return out_;
+        }
+
+        /// <summary>
+        /// A MODULE PATH IS NOT A NAME (§10.2). The ref grammar starts a
+        /// name with a letter or <c>@</c>, so <c>./local/thing</c> 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.
+        /// </summary>
+        public static List<object> ResolveFrom(object from)
+        {
+            return new List<object> { from };
+        }
+    }
+}

package/project/.sdk/tm/csharp/feature/secrets/plugin/Types.cs

@@ -0,0 +1,351 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (csharp/src/Types.cs)
+// 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.
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+
+namespace Voxgig.Plugin
+{
+    /// <summary>
+    /// Shared types and the value helpers every module reads data through.
+    ///
+    /// <para>Deliberately small: the design's §19 budget says the library
+    /// owns naming, configuration, lifecycle, ordering, binding and
+    /// teardown, and nothing else.</para>
+    ///
+    /// <para>THE VALUE MODEL IS PLAIN <c>object</c>, with ONE csharp
+    /// spelling per JSON type: <c>null</c>, <c>bool</c>, <c>double</c>,
+    /// <c>string</c>, <c>List&lt;object&gt;</c> and a
+    /// <c>SortedDictionary&lt;string,object&gt;</c> ordered
+    /// <c>Ordinal</c>. Two of those choices are corpus-visible and both
+    /// are explained where they are made: every number is a double, and
+    /// every string comparison is ordinal.</para>
+    /// </summary>
+    public static class Types
+    {
+        /// §5.1's seven statuses, and no more. A port that adds an eighth
+        /// is diverging.
+        public static readonly string[] STATUSES =
+        {
+            "declared", "loaded", "pending", "live", "failed", "loading", "closing",
+        };
+
+        /// §12's detail fields, IN THIS FIXED ORDER. The order is part of
+        /// the contract, not a formatting preference: an earlier draft
+        /// named six fields while other sections promised diagnostics that
+        /// had nowhere to go, which would have left each port inventing
+        /// its own order and breaking message parity.
+        public static readonly string[] DETAIL_ORDER =
+        {
+            "host", "ref", "name", "tag", "point", "key", "capability", "range",
+            "version", "match", "candidates", "cycle", "holders", "refs", "path", "cause",
+        };
+
+        /// <summary>
+        /// A map, ORDINALLY sorted.
+        ///
+        /// <para>NOT the default comparer. <c>Comparer&lt;string&gt;.Default</c>
+        /// is CULTURE-SENSITIVE, so `"a"` before `"B"` in one locale and
+        /// after it in another - and this port sorts refs, keys and names
+        /// for exactly the reason every other port does: the corpus pins a
+        /// byte-wise order (`@` 0x40, uppercase, lowercase). A culture
+        /// comparer is a port that passes on the build machine.</para>
+        /// </summary>
+        public static SortedDictionary<string, object> NewMap()
+        {
+            return new SortedDictionary<string, object>(StringComparer.Ordinal);
+        }
+
+        public static SortedDictionary<string, object> Map(object value)
+        {
+            return value as SortedDictionary<string, object>;
+        }
+
+        public static List<object> List(object value)
+        {
+            return value as List<object>;
+        }
+
+        public static string Str(object value)
+        {
+            return value as string;
+        }
+
+        public static double? Num(object value)
+        {
+            return value is double d ? d : (double?)null;
+        }
+
+        /// <summary>
+        /// An INTEGER, and only when the value is one. §7's band is an
+        /// integer the document wrote as one; <c>true</c> and <c>"2"</c>
+        /// are not bands, and a port that coerced them would accept
+        /// documents the canonical rejects.
+        /// </summary>
+        public static long? AsInt(object value)
+        {
+            if (!(value is double d) || d != Math.Floor(d) || double.IsInfinity(d))
+            {
+                return null;
+            }
+            return (long)d;
+        }
+
+        /// The value at a key, or null. Absence and null read the same here.
+        public static object Get(object node, string key)
+        {
+            var map = Map(node);
+            if (null == map)
+            {
+                return null;
+            }
+            return map.TryGetValue(key, out var value) ? value : null;
+        }
+
+        /// PRESENCE, which is what distinguishes an authored null from absence.
+        public static bool Has(object node, string key)
+        {
+            var map = Map(node);
+            return null != map && map.ContainsKey(key);
+        }
+
+        public static object At(object node, int index)
+        {
+            var list = List(node);
+            return null == list || list.Count <= index ? null : list[index];
+        }
+
+        /// The keys of a map, sorted - which the map already is.
+        public static List<string> Keys(object node)
+        {
+            var map = Map(node);
+            var out_ = new List<string>();
+            if (null == map)
+            {
+                return out_;
+            }
+            out_.AddRange(map.Keys);
+            return out_;
+        }
+
+        /// <summary>
+        /// Ruby's truthiness, which is not csharp's <c>if</c>: present,
+        /// and not <c>false</c>. <c>0</c>, <c>""</c> and <c>[]</c> are all
+        /// values the corpus distinguishes from absence.
+        /// </summary>
+        public static bool Truthy(object value)
+        {
+            return null != value && !(value is bool b && !b);
+        }
+
+        /// <summary>
+        /// JSON equality: same type, then same value.
+        ///
+        /// <para><c>true</c> is not <c>1</c> and <c>1</c> is not
+        /// <c>"1"</c> - `capability/match` has an entry for each
+        /// direction. CSHARP NEEDS NO GUARD FOR THAT: a boxed bool and a
+        /// boxed double are different types and <c>Equals</c> is false
+        /// between them. What it DOES need is the one-number-type rule
+        /// kept at the parser, because a boxed <c>int</c> would compare
+        /// unequal to the <c>double</c> the parser produced for the same
+        /// literal.</para>
+        /// </summary>
+        public static bool Same(object a, object b)
+        {
+            var ma = Map(a);
+            var mb = Map(b);
+            if (null != ma || null != mb)
+            {
+                if (null == ma || null == mb || ma.Count != mb.Count)
+                {
+                    return false;
+                }
+                foreach (var pair in ma)
+                {
+                    if (!mb.TryGetValue(pair.Key, out var other) || !Same(pair.Value, other))
+                    {
+                        return false;
+                    }
+                }
+                return true;
+            }
+
+            var la = List(a);
+            var lb = List(b);
+            if (null != la || null != lb)
+            {
+                if (null == la || null == lb || la.Count != lb.Count)
+                {
+                    return false;
+                }
+                for (var i = 0; i < la.Count; i++)
+                {
+                    if (!Same(la[i], lb[i]))
+                    {
+                        return false;
+                    }
+                }
+                return true;
+            }
+
+            return null == a ? null == b : a.Equals(b);
+        }
+
+        public static object Copy(object value)
+        {
+            var map = Map(value);
+            if (null != map)
+            {
+                var out_ = NewMap();
+                foreach (var pair in map)
+                {
+                    out_[pair.Key] = Copy(pair.Value);
+                }
+                return out_;
+            }
+            var list = List(value);
+            if (null != list)
+            {
+                var out_ = new List<object>();
+                foreach (var item in list)
+                {
+                    out_.Add(Copy(item));
+                }
+                return out_;
+            }
+            return value;
+        }
+
+        /// A list of strings as a list of values, for a detail field.
+        public static List<object> Strings(IEnumerable<string> items)
+        {
+            var out_ = new List<object>();
+            foreach (var s in items)
+            {
+                out_.Add(s);
+            }
+            return out_;
+        }
+
+        /// ORDINAL, for the same reason <see cref="NewMap"/> is.
+        public static void SortStrings(List<string> items)
+        {
+            items.Sort(StringComparer.Ordinal);
+        }
+
+        /// <summary>
+        /// A STABLE sort.
+        ///
+        /// <para><c>List&lt;T&gt;.Sort</c> is an INTROSORT and is NOT
+        /// stable, and the canonical's comparators fall through to a
+        /// `pos` or ref tie-break that javascript's stable sort resolves
+        /// by position. So this decorates with the original index and
+        /// breaks the last tie on it - the same shape ruby and lua need,
+        /// for the same reason.</para>
+        /// </summary>
+        public static List<T> StableSorted<T>(List<T> items, Comparison<T> compare)
+        {
+            var source = items.ToArray();
+            var order = new int[source.Length];
+            for (var i = 0; i < order.Length; i++)
+            {
+                order[i] = i;
+            }
+            Array.Sort(order, (x, y) =>
+            {
+                var c = compare(source[x], source[y]);
+                return 0 != c ? c : x.CompareTo(y);
+            });
+            var out_ = new List<T>(source.Length);
+            foreach (var at in order)
+            {
+                out_.Add(source[at]);
+            }
+            return out_;
+        }
+
+        /// A detail map, spelled once rather than at forty call sites.
+        public static SortedDictionary<string, object> Details(params object[] pairs)
+        {
+            var out_ = NewMap();
+            for (var i = 0; i + 1 < pairs.Length; i += 2)
+            {
+                out_[(string)pairs[i]] = pairs[i + 1];
+            }
+            return out_;
+        }
+
+        /// <summary>
+        /// <c>plugin/&lt;code&gt;: &lt;text&gt; [&lt;key&gt;=&lt;value&gt; ...]</c>
+        ///
+        /// <para>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.</para>
+        /// </summary>
+        public static string FormatError(string code, string text, object details)
+        {
+            var parts = new List<string>();
+            foreach (var key in DETAIL_ORDER)
+            {
+                if (!Has(details, key))
+                {
+                    continue;
+                }
+                parts.Add(key + "=" + Json.Write(Get(details, key)));
+            }
+            var tail = 0 == parts.Count ? "" : " [" + string.Join(" ", parts) + "]";
+            return "plugin/" + code + ": " + text + tail;
+        }
+
+        /// Throw a §12 error. One spelling, so every raise site reads the same.
+        public static void Fail(string code, string text, object details)
+        {
+            throw new PluginException(code, text, details);
+        }
+
+        /// <summary>
+        /// The §12 code of an exception, or "" for one this library did
+        /// not raise. The corpus compares by code, so the driver needs one
+        /// place that knows how to read it.
+        /// </summary>
+        public static string CodeOf(Exception err)
+        {
+            return err is PluginException pe ? pe.Code : "";
+        }
+
+        /// Invariant formatting, so a number in a message never depends on
+        /// the machine's locale.
+        public static string NumText(double n)
+        {
+            if (n == Math.Floor(n) && !double.IsInfinity(n) && Math.Abs(n) < 1e15)
+            {
+                return ((long)n).ToString(CultureInfo.InvariantCulture);
+            }
+            return n.ToString("R", CultureInfo.InvariantCulture);
+        }
+    }
+
+    /// <summary>
+    /// Every error carries a §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.
+    /// </summary>
+    public class PluginException : Exception
+    {
+        public readonly string Code;
+        public readonly string Text;
+        public readonly object Details;
+
+        public PluginException(string code, string text, object details)
+            : base(Types.FormatError(code, text, details))
+        {
+            Code = code;
+            Text = text;
+            Details = details;
+        }
+    }
+}