@voxgig/sdkgen 4.8.3 → 4.10.0

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

@@ -0,0 +1,295 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (csharp/src/Order.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>
+    /// Ordering (§7) - one rule, one place.
+    ///
+    /// <para>sdkgen grew two special cases in <c>makeOptions</c> and the
+    /// third was not far off. This sort is the whole replacement, and the
+    /// tiers are: constraints (before/after edges, by ref or by name),
+    /// then bands (integer, lower first, default 0), then declaration ties
+    /// by <c>pos</c>.</para>
+    ///
+    /// <para>CONSTRAINTS BEAT BANDS precisely so the correct tool wins
+    /// when both are present. A band expresses a genuine cross-cutting
+    /// layer; a constraint expresses a relationship between two specific
+    /// things; and a band chosen by trial and error to fix an ordering bug
+    /// is a bug wearing a number.</para>
+    /// </summary>
+    public static class Order
+    {
+        /// One thing to place: its ref, its position, and its block as authored.
+        public sealed class Binding
+        {
+            public readonly string Ref;
+            public readonly double Pos;
+            public readonly object OrderBlock;
+
+            public Binding(string eref, double pos, object order)
+            {
+                Ref = eref;
+                Pos = pos;
+                OrderBlock = order;
+            }
+        }
+
+        public static List<string> ResolveOrder(List<Binding> bindings, object pin)
+        {
+            var byref = new Dictionary<string, Binding>(StringComparer.Ordinal);
+            foreach (var b in bindings)
+            {
+                byref[b.Ref] = b;
+            }
+
+            // Constraints are edges. A constraint naming an ABSENT binding
+            // is satisfied VACUOUSLY (§7) - a plugin ordered `after:
+            // 'test'` must load in a host with no test plugin. That is
+            // sdkgen's __after__ behaviour, kept.
+            var edges = new SortedDictionary<string, List<string>>(StringComparer.Ordinal);
+            var indeg = new SortedDictionary<string, int>(StringComparer.Ordinal);
+            foreach (var b in bindings)
+            {
+                edges[b.Ref] = new List<string>();
+                indeg[b.Ref] = 0;
+            }
+
+            foreach (var b in bindings)
+            {
+                var block = b.OrderBlock;
+                // An ABSENT constraint and an EMPTY LIST are both "no
+                // constraint".
+                if (Declared(Types.Get(block, "after")))
+                {
+                    foreach (var t in Targets(Types.Get(block, "after"), bindings))
+                    {
+                        edges[t].Add(b.Ref);
+                    }
+                }
+                if (Declared(Types.Get(block, "before")))
+                {
+                    edges[b.Ref].AddRange(Targets(Types.Get(block, "before"), bindings));
+                }
+            }
+
+            foreach (var tos in edges.Values)
+            {
+                foreach (var to in tos)
+                {
+                    indeg[to] = indeg[to] + 1;
+                }
+            }
+
+            // Stable topological sort. Among ready nodes, band first
+            // (lower runs first), then `pos` - the position the DOCUMENT
+            // visibly states, not the order instances happened to load and
+            // not the incarnation `seq`.
+            var out_ = new List<string>();
+            var ready = new List<Binding>();
+            foreach (var b in bindings)
+            {
+                if (0 == indeg[b.Ref])
+                {
+                    ready.Add(b);
+                }
+            }
+
+            while (0 < ready.Count)
+            {
+                ready = Types.StableSorted(ready, (x, y) =>
+                {
+                    var bx = Band(x.OrderBlock);
+                    var by = Band(y.OrderBlock);
+                    if (bx != by)
+                    {
+                        return bx < by ? -1 : 1;
+                    }
+                    return x.Pos.CompareTo(y.Pos);
+                });
+                var next = ready[0];
+                ready.RemoveAt(0);
+                out_.Add(next.Ref);
+                foreach (var to in edges[next.Ref])
+                {
+                    indeg[to] = indeg[to] - 1;
+                    if (0 == indeg[to])
+                    {
+                        ready.Add(byref[to]);
+                    }
+                }
+            }
+
+            if (out_.Count != bindings.Count)
+            {
+                var stuck = new List<string>();
+                foreach (var b in bindings)
+                {
+                    if (!out_.Contains(b.Ref))
+                    {
+                        stuck.Add(b.Ref);
+                    }
+                }
+                Types.Fail("plugin_order_cycle",
+                           "before/after constraints cycle: " + string.Join(" -> ", stuck),
+                           Types.Details("cycle", Types.Strings(stuck)));
+            }
+
+            return ApplyPin(out_, edges, pin);
+        }
+
+        /// An integer, and only an integer: <c>true</c> and <c>"2"</c> are not bands.
+        public static long Band(object block)
+        {
+            return Types.AsInt(Types.Get(block, "band")) ?? 0;
+        }
+
+        /// <summary>
+        /// Was a constraint stated? An absent value and an EMPTY LIST are
+        /// both no-constraint - and an empty list is TRUTHY in most
+        /// languages, which is exactly how this class of bug survives a
+        /// reading.
+        /// </summary>
+        public static bool Declared(object spec)
+        {
+            if (null == spec)
+            {
+                return false;
+            }
+            var list = Types.List(spec);
+            if (null != list)
+            {
+                foreach (var one in list)
+                {
+                    if (!"".Equals(one))
+                    {
+                        return true;
+                    }
+                }
+                return false;
+            }
+            return !"".Equals(spec);
+        }
+
+        /// <summary>
+        /// One spelling or a LIST of them. A list fans out to the UNION of
+        /// what each names, so after: ['a','b'] means after BOTH, and the
+        /// same instance named twice - once by name, once by ref - is one
+        /// edge.
+        /// </summary>
+        public static List<string> Targets(object spec, List<Binding> nodes)
+        {
+            var specs = Types.List(spec) ?? new List<object> { spec };
+            var hit = new List<string>();
+            foreach (var one in specs)
+            {
+                var want = Types.Str(one);
+                if (null == want)
+                {
+                    continue;
+                }
+                foreach (var b in nodes)
+                {
+                    if (hit.Contains(b.Ref))
+                    {
+                        continue;
+                    }
+                    if (b.Ref == want || Refs.RefName(b.Ref) == want)
+                    {
+                        hit.Add(b.Ref);
+                    }
+                }
+            }
+            return hit;
+        }
+
+        /// <summary>
+        /// A PIN IS NOT A CONSTRAINT (§7).
+        ///
+        /// <para>Constraints and bands are negotiable by definition - they
+        /// are what plugins and documents say they want. A pin is the host
+        /// stating a structural invariant of its own architecture, which
+        /// is a different kind of claim and must not lose a tie to a
+        /// document. So a pin PLACES the binding at the named end, and an
+        /// ordering that would move it away is
+        /// <c>plugin_order_pinned</c> - rejected, not honoured into a
+        /// broken wrap.</para>
+        /// </summary>
+        private static List<string> ApplyPin(
+            List<string> order, SortedDictionary<string, List<string>> edges, object pin)
+        {
+            if (null == pin)
+            {
+                return order;
+            }
+
+            var out_ = new List<string>(order);
+
+            // SORTED, not insertion order. A pin map is data - it can
+            // arrive from a host's own construction options in any order,
+            // and two names pinned to the same end are order-sensitive.
+            foreach (var name in Types.Keys(pin))
+            {
+                var want = Types.Get(pin, name);
+                var idx = -1;
+                for (var i = 0; i < out_.Count; i++)
+                {
+                    if (Refs.RefName(out_[i]) == name)
+                    {
+                        idx = i;
+                        break;
+                    }
+                }
+                if (idx < 0)
+                {
+                    continue;
+                }
+
+                // `first`/`outermost` is index 0; `last`/`innermost` is
+                // the end. §6.2 makes the first chain binding outermost,
+                // which is why the vocabulary is positional and why the
+                // two spellings pair this way.
+                var wantfirst = "first".Equals(want) || "outermost".Equals(want);
+                var eref = out_[idx];
+                out_.RemoveAt(idx);
+                if (wantfirst)
+                {
+                    out_.Insert(0, eref);
+                }
+                else
+                {
+                    out_.Add(eref);
+                }
+            }
+
+            // Now check that the placement did not break a constraint.
+            // This is the half that makes a pin a rejection rather than an
+            // override: the host wins on position, but it does not get to
+            // silently discard a relationship a plugin declared.
+            var at = new Dictionary<string, int>(StringComparer.Ordinal);
+            for (var i = 0; i < out_.Count; i++)
+            {
+                at[out_[i]] = i;
+            }
+            foreach (var pair in edges)
+            {
+                foreach (var to in pair.Value)
+                {
+                    if (at[pair.Key] <= at[to])
+                    {
+                        continue;
+                    }
+                    Types.Fail("plugin_order_pinned",
+                               "a pin would move a binding an ordering constrains: "
+                               + pair.Key + " must precede " + to,
+                               Types.Details("before", pair.Key, "after", to));
+                }
+            }
+
+            return out_;
+        }
+    }
+}

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

@@ -0,0 +1,113 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (csharp/src/Plugin.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>
+    /// The canonical surface <c>make parity</c> checks (AGENTS.md §4).
+    ///
+    /// <para>Small on purpose (§19): everything else is methods on
+    /// <see cref="Host"/> and <see cref="Inst"/>, because a library that
+    /// grows a second public entry point per feature is a library twenty
+    /// ports pay for twice.</para>
+    ///
+    /// <para>This class FORWARDS rather than implements. The surface is
+    /// visible in one place, and a name that stops existing stops existing
+    /// here loudly.</para>
+    /// </summary>
+    public static class Plugin
+    {
+        public static Host MakeHost(object options)
+        {
+            return Host.MakeHost(options);
+        }
+
+        public static Catalog MakeCatalog(List<Definition> definitions)
+        {
+            return Catalog.MakeCatalog(definitions);
+        }
+
+        public static SortedDictionary<string, object> ParseRef(object eref)
+        {
+            return Refs.ParseRef(eref);
+        }
+
+        public static string FormatRef(object name, object tag)
+        {
+            return Refs.FormatRef(name, tag);
+        }
+
+        public static bool CheckName(object name)
+        {
+            return Refs.CheckName(name);
+        }
+
+        public static bool CheckTag(object tag)
+        {
+            return Refs.CheckTag(tag);
+        }
+
+        public static string CanonRef(object eref)
+        {
+            return Refs.CanonRef(eref);
+        }
+
+        public static SortedDictionary<string, object> NormalizeConfig(object input)
+        {
+            return Config.NormalizeConfig(input);
+        }
+
+        public static SortedDictionary<string, object> ResolveOptions(object input)
+        {
+            return Config.ResolveOptions(input);
+        }
+
+        public static List<string> ResolveOrder(List<Order.Binding> bindings, object pin)
+        {
+            return Order.ResolveOrder(bindings, pin);
+        }
+
+        public static List<object> ResolveCandidates(string name, object sources)
+        {
+            return Resolve.ResolveCandidates(name, sources);
+        }
+
+        public static List<object> ResolveFrom(object from)
+        {
+            return Resolve.ResolveFrom(from);
+        }
+
+        public static List<object> ResolveCapability(object req, List<object> candidates)
+        {
+            return Capability.ResolveCapability(req, candidates);
+        }
+
+        public static SortedDictionary<string, object> ResolveGraph(object nodes)
+        {
+            return Graph.ResolveGraph(nodes);
+        }
+
+        public static SortedDictionary<string, object> ApplyEnv(object input)
+        {
+            return Env.ApplyEnv(input);
+        }
+
+        public static SortedDictionary<string, object> ParseRange(object range)
+        {
+            return Version.ParseRange(range);
+        }
+
+        public static bool Satisfies(object version, object range)
+        {
+            return Version.Satisfies(version, range);
+        }
+
+        public static string CodeOf(Exception err)
+        {
+            return Types.CodeOf(err);
+        }
+    }
+}

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

@@ -0,0 +1,177 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (csharp/src/Point.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>
+    /// Extension points (§6). Three kinds, chosen because they are what
+    /// the two existing systems actually needed, and no more.
+    ///
+    /// <para>A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes
+    /// deactivation possible: sdkgen's <c>utility.fetcher = wrapped</c> is
+    /// not undoable, but "this instance holds slot 3 of the request chain"
+    /// is undoable in O(1). OSGi named it the whiteboard pattern in 2004,
+    /// in a paper called <i>Listeners Considered Harmful</i>, and for
+    /// exactly this reason.</para>
+    /// </summary>
+    public static class Point
+    {
+        /// The next link of a chain (§6.2), or the base at the end of it.
+        public delegate object NextFn(object[] args);
+
+        /// <summary>
+        /// EVERY binding has one signature, whatever kind of point it is
+        /// on: a hook and a provider ignore the <c>next</c> they are
+        /// handed, a chain uses it. One signature is what lets
+        /// <c>Bound</c> return a single list the three callers share,
+        /// rather than three parallel registries that can disagree about
+        /// which instance holds slot 3.
+        /// </summary>
+        public delegate object BindFn(NextFn next, object[] args);
+
+        public sealed class Bound
+        {
+            public readonly string Ref;
+            public readonly string PointName;
+            public readonly BindFn Func;
+            public readonly long Band;
+
+            public Bound(string eref, string point, BindFn func, long band)
+            {
+                Ref = eref;
+                PointName = point;
+                Func = func;
+                Band = band;
+            }
+
+            public Bound WithBand(long band)
+            {
+                return new Bound(Ref, PointName, Func, band);
+            }
+        }
+
+        /// §6.1: "fan-out" is not one answer but four.
+        public static readonly string[] MODES = { "emit", "parallel", "serial", "bail" };
+
+        /// Fan-out. Return values are ignored except in <c>bail</c>.
+        public static object Emit(List<Bound> bindings, string mode, object arg)
+        {
+            if ("bail" == mode)
+            {
+                // Stops at the first binding that RETURNS A VALUE - the
+                // "handled, stop" case. A `null` RETURN DECLINES (§6.1).
+                // Not truthiness - `false`, `0` and `""` are values.
+                foreach (var b in bindings)
+                {
+                    var v = b.Func(null, new object[] { arg });
+                    if (null != v)
+                    {
+                        return v;
+                    }
+                }
+                return null;
+            }
+
+            var errors = new List<object>();
+            foreach (var b in bindings)
+            {
+                try
+                {
+                    b.Func(null, new object[] { arg });
+                }
+                catch (Exception e)
+                {
+                    // `emit` raises synchronously; the collecting modes
+                    // gather.
+                    if ("emit" == mode)
+                    {
+                        throw;
+                    }
+                    errors.Add(e.Message);
+                }
+            }
+            return "emit" == mode ? null : (object)errors;
+        }
+
+        /// <summary>
+        /// Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (§6.2).
+        ///
+        /// <para>Plugins receive <c>next</c> as an argument; they never
+        /// see or store the previous value of anything. A plugin that
+        /// stashes <c>next</c> and calls it after deactivation is a bug
+        /// the host cannot prevent, and this says so rather than
+        /// pretending otherwise.</para>
+        /// </summary>
+        public static NextFn Compose(List<Bound> bindings, NextFn base_)
+        {
+            var next = base_;
+            for (var i = bindings.Count - 1; 0 <= i; i--)
+            {
+                // Locals captured per iteration, so each layer closes over
+                // its own pair - csharp's foreach-variable capture rule
+                // changed in C# 5 and a `for` index would still need this.
+                var func = bindings[i].Func;
+                var inner = next;
+                next = args => func(inner, args);
+            }
+            return next;
+        }
+
+        public sealed class Picked
+        {
+            public readonly Bound Winner;
+            public readonly List<string> Shadowed;
+
+            public Picked(Bound winner, List<string> shadowed)
+            {
+                Winner = winner;
+                Shadowed = shadowed;
+            }
+        }
+
+        /// <summary>
+        /// At most one live implementation (§6.3). The winner is the
+        /// highest band, ties broken by ref sort, and THE LOSERS ARE
+        /// VISIBLE rather than silently ignored.
+        /// </summary>
+        public static Picked Provider(List<Bound> bindings, object spec)
+        {
+            if (0 == bindings.Count)
+            {
+                return new Picked(null, new List<string>());
+            }
+
+            if (Types.Truthy(Types.Get(spec, "exclusive")) && 1 < bindings.Count)
+            {
+                var refs = new List<string>();
+                foreach (var b in bindings)
+                {
+                    refs.Add(b.Ref);
+                }
+                Types.SortStrings(refs);
+                Types.Fail("plugin_point_exclusive",
+                           "point is exclusive and has " + bindings.Count + " bindings: "
+                           + string.Join(", ", refs),
+                           Types.Details("refs", Types.Strings(refs)));
+            }
+
+            var ranked = Types.StableSorted(bindings, (a, b) =>
+            {
+                if (a.Band != b.Band)
+                {
+                    return a.Band < b.Band ? 1 : -1; // higher band first
+                }
+                return string.CompareOrdinal(a.Ref, b.Ref);
+            });
+            var shadowed = new List<string>();
+            for (var i = 1; i < ranked.Count; i++)
+            {
+                shadowed.Add(ranked[i].Ref);
+            }
+            return new Picked(ranked[0], shadowed);
+        }
+    }
+}