@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/php/feature/secrets/plugin/Order.php

@@ -0,0 +1,260 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Order.php)
+// 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.
+
+/**
+ * Ordering (§7) - one rule, one place.
+ *
+ * sdkgen grew two special cases in `makeOptions` (`test`, then `station`)
+ * and the third was not far off. This sort is the whole replacement, and
+ * the tiers are in this order for a reason:
+ *
+ *   1 constraints   before/after edges, by ref or by name
+ *   2 bands         integer, lower first, default 0
+ *   3 declaration   ties break by `pos`
+ *
+ * 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.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+/**
+ * @param array<int,array<string,mixed>> $bindings
+ * @param array<string,string>|null $pin
+ * @return string[]
+ */
+function resolve_order(array $bindings, ?array $pin = null): array
+{
+    $nodes = array_values($bindings);
+    $byref = [];
+    foreach ($nodes as $b) {
+        $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.
+    $edges = [];
+    foreach ($nodes as $b) {
+        $edges[$b['ref']] = [];
+    }
+
+    foreach ($nodes as $b) {
+        $block = $b['order'] ?? [];
+        if (!is_array($block)) {
+            $block = [];
+        }
+        // An ABSENT constraint and an EMPTY LIST are both "no constraint".
+        if (order_declared($block['after'] ?? null)) {
+            foreach (order_targets($block['after'], $nodes) as $t) {
+                $edges[$t][] = $b['ref'];
+            }
+        }
+        if (order_declared($block['before'] ?? null)) {
+            foreach (order_targets($block['before'], $nodes) as $t) {
+                $edges[$b['ref']][] = $t;
+            }
+        }
+    }
+
+    // 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`.
+    $indeg = [];
+    foreach ($nodes as $b) {
+        $indeg[$b['ref']] = 0;
+    }
+    foreach ($edges as $tos) {
+        foreach ($tos as $to) {
+            $indeg[$to]++;
+        }
+    }
+
+    $out = [];
+    $ready = [];
+    foreach ($nodes as $b) {
+        if (0 === $indeg[$b['ref']]) {
+            $ready[] = $b;
+        }
+    }
+
+    while (!empty($ready)) {
+        $ready = Util::stable_sort_by($ready, static function ($b) {
+            return [order_band($b), $b['pos'] ?? 0];
+        });
+        $nxt = array_shift($ready);
+        $out[] = $nxt['ref'];
+        foreach ($edges[$nxt['ref']] as $to) {
+            $indeg[$to]--;
+            if (0 === $indeg[$to]) {
+                $ready[] = $byref[$to];
+            }
+        }
+    }
+
+    if (count($out) !== count($nodes)) {
+        $stuck = [];
+        foreach ($nodes as $b) {
+            if (!in_array($b['ref'], $out, true)) {
+                $stuck[] = $b['ref'];
+            }
+        }
+        fail_with('plugin_order_cycle',
+                  'before/after constraints cycle: ' . implode(' -> ', $stuck),
+                  ['cycle' => $stuck]);
+    }
+
+    return applypin($out, $edges, $pin);
+}
+
+/**
+ * @param array<string,mixed> $binding
+ */
+function order_band(array $binding): int
+{
+    $block = $binding['order'] ?? [];
+    $value = is_array($block) ? ($block['band'] ?? null) : null;
+    // `is_int` and not `is_numeric`: §7's band is an integer, and PHP
+    // reads `true` as neither an int nor a float, so the boolean case
+    // falls out here the way it does in ruby.
+    return is_int($value) ? $value : 0;
+}
+
+/**
+ * Was a constraint stated? An absent value and an EMPTY LIST are both
+ * no-constraint - and `[]` is FALSY in php, which is the mirror image of
+ * the ruby trap: a plain truthiness test gets the empty list right here
+ * and the empty STRING wrong, so this tests the spelling either way.
+ *
+ * @param mixed $spec
+ */
+function order_declared($spec): bool
+{
+    if (null === $spec) {
+        return false;
+    }
+    if (is_array($spec)) {
+        foreach ($spec as $one) {
+            if ('' !== $one) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return '' !== $spec;
+}
+
+/**
+ * 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.
+ *
+ * @param mixed $spec
+ * @param array<int,array<string,mixed>> $nodes
+ * @return string[]
+ */
+function order_targets($spec, array $nodes): array
+{
+    $specs = is_array($spec) ? $spec : [$spec];
+    $hit = [];
+    foreach ($specs as $one) {
+        foreach ($nodes as $b) {
+            if (in_array($b['ref'], $hit, true)) {
+                continue;
+            }
+            if ($b['ref'] === $one || refname($b['ref']) === $one) {
+                $hit[] = $b['ref'];
+            }
+        }
+    }
+    return $hit;
+}
+
+/**
+ * A PIN IS NOT A CONSTRAINT (§7).
+ *
+ * Constraints and bands are negotiable by definition - they are what
+ * plugins and documents say they want, and the sort's job is to satisfy
+ * them all. 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 `plugin_order_pinned` - rejected, not honoured into a
+ * broken wrap.
+ *
+ * @param string[] $order
+ * @param array<string,string[]> $edges
+ * @param array<string,string>|null $pin
+ * @return string[]
+ */
+function applypin(array $order, array $edges, ?array $pin): array
+{
+    if (null === $pin) {
+        return $order;
+    }
+
+    $out = $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 (`{b:'first', a:'first'}` and
+    // `{a:'first', b:'first'}` give different results). PHP arrays keep
+    // insertion order and a Go map has none at all, so leaving it unstated
+    // made the same declaration mean different things in different ports.
+    foreach (Util::sortedkeys($pin) as $name) {
+        $want = $pin[$name];
+        $idx = null;
+        foreach ($out as $i => $r) {
+            if (refname($r) === $name) {
+                $idx = $i;
+                break;
+            }
+        }
+        if (null === $idx) {
+            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.
+        $wantfirst = in_array($want, ['first', 'outermost'], true);
+        $ref = $out[$idx];
+        array_splice($out, $idx, 1);
+        if ($wantfirst) {
+            array_unshift($out, $ref);
+        } else {
+            $out[] = $ref;
+        }
+    }
+
+    // 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.
+    $at = [];
+    foreach ($out as $i => $r) {
+        $at[$r] = $i;
+    }
+    foreach ($edges as $from => $tos) {
+        foreach ($tos as $to) {
+            if ($at[$from] <= $at[$to]) {
+                continue;
+            }
+            fail_with('plugin_order_pinned',
+                      'a pin would move a binding an ordering constrains: '
+                      . $from . ' must precede ' . $to,
+                      ['before' => $from, 'after' => $to]);
+        }
+    }
+
+    return $out;
+}

package/project/.sdk/tm/php/feature/secrets/plugin/Point.php

@@ -0,0 +1,129 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Point.php)
+// 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.
+
+/**
+ * Extension points (§6). Three kinds, chosen because they are what the two
+ * existing systems actually needed, and no more.
+ *
+ * A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes
+ * deactivation possible: sdkgen's `utility.fetcher = wrapped` 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 *Listeners Considered Harmful*, and for exactly this
+ * reason.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+/**
+ * §6.1: "fan-out" is not one answer but four. In a language with
+ * asynchrony, "call every binding" hides a decision - start them all and
+ * wait, await each in turn, or do not wait - and a design that leaves it
+ * unsaid gets four different answers from four ports, in the concurrency
+ * behaviour of production code no corpus entry happens to cover.
+ */
+const MODES = ['emit', 'parallel', 'serial', 'bail'];
+
+/**
+ * Fan-out. Return values are ignored except in `bail`.
+ *
+ * @param array<int,array<string,mixed>> $bindings
+ * @param mixed $arg
+ * @return mixed
+ */
+function point_emit(array $bindings, string $mode, $arg)
+{
+    if ('bail' === $mode) {
+        // Stops at the first binding that RETURNS A VALUE - the "handled,
+        // stop" case. A `null` RETURN DECLINES (§6.1): php has one way to
+        // say nothing, and the model's rule is written to that rather than
+        // to JavaScript's null/undefined pair. `null !== $v`, NOT
+        // `if ($v)` - `false`, `0` and `''` are values.
+        foreach ($bindings as $b) {
+            $v = ($b['fn'])($arg);
+            if (null !== $v) {
+                return $v;
+            }
+        }
+        return null;
+    }
+
+    $errors = [];
+    foreach ($bindings as $b) {
+        try {
+            ($b['fn'])($arg);
+        } catch (\Throwable $e) {
+            // `emit` raises synchronously; the collecting modes gather.
+            if ('emit' === $mode) {
+                throw $e;
+            }
+            $errors[] = $e;
+        }
+    }
+    return 'emit' === $mode ? null : $errors;
+}
+
+/**
+ * Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (§6.2).
+ *
+ * Recomputed by the host whenever the live set changes, and cached between
+ * changes. Plugins receive `next` as an argument; they never see or store
+ * the previous value of anything. A plugin that stashes `next` and calls
+ * it after deactivation is a bug the host cannot prevent, and this says so
+ * rather than pretending otherwise.
+ *
+ * @param array<int,array<string,mixed>> $bindings
+ */
+function compose(array $bindings, callable $base): callable
+{
+    $nxt = $base;
+    for ($i = count($bindings) - 1; $i >= 0; $i--) {
+        $fn = $bindings[$i]['fn'];
+        $inner = $nxt;
+        // `use` captures BY VALUE at creation, so each layer closes over
+        // its own pair without the block-local dance ruby needs.
+        $nxt = static function (...$args) use ($fn, $inner) {
+            return $fn($inner, ...$args);
+        };
+    }
+    return $nxt;
+}
+
+/**
+ * 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.
+ *
+ * @param array<int,array<string,mixed>> $bindings
+ * @param array<string,mixed> $spec
+ * @return array{winner:array<string,mixed>|null,shadowed:string[]}
+ */
+function point_provider(array $bindings, array $spec): array
+{
+    if (empty($bindings)) {
+        return ['winner' => null, 'shadowed' => []];
+    }
+
+    if (Util::truthy($spec['exclusive'] ?? null) && count($bindings) > 1) {
+        $refs = Util::sortstrings(array_map(static function ($b) {
+            return $b['ref'];
+        }, $bindings));
+        fail_with('plugin_point_exclusive',
+                  'point is exclusive and has ' . count($bindings)
+                  . ' bindings: ' . implode(', ', $refs),
+                  ['refs' => $refs]);
+    }
+
+    $ranked = Util::stable_sort_by($bindings, static function ($b) {
+        return [-$b['band'], $b['ref']];
+    });
+    $shadowed = [];
+    foreach (array_slice($ranked, 1) as $b) {
+        $shadowed[] = $b['ref'];
+    }
+    return ['winner' => $ranked[0], 'shadowed' => $shadowed];
+}

package/project/.sdk/tm/php/feature/secrets/plugin/Ref.php

@@ -0,0 +1,169 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Ref.php)
+// 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.
+
+/**
+ * Identity: name+tag, written `name$tag` (§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.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+/**
+ * §4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+ *
+ * \A and \z, NOT ^ and $. PCRE's `$` matches BEFORE A TRAILING NEWLINE and
+ * its `^`/`$` become line anchors under `/m`, so a `^...$` spelling admits
+ * `"stripe\n"` as a name - the same hole the ruby port surfaced in python,
+ * and the reason four `#trailing-newline` entries exist.
+ */
+const NAME_RE = '/\A[a-zA-Z@][a-zA-Z0-9.~_\-\/]*\z/';
+
+/**
+ * §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.
+ */
+const TAG_RE = '/\A[a-zA-Z0-9.~_-]+\z/';
+
+const REF_MAX = 1024;
+
+/**
+ * @param mixed $name
+ */
+function check_name($name): bool
+{
+    if (!is_string($name)) {
+        return false;
+    }
+    if ('' === $name || REF_MAX < strlen($name)) {
+        return false;
+    }
+    return 1 === preg_match(NAME_RE, $name);
+}
+
+/**
+ * @param mixed $tag
+ */
+function check_tag($tag): bool
+{
+    if (!is_string($tag)) {
+        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 ('' === $tag) {
+        return true;
+    }
+    if (REF_MAX < strlen($tag)) {
+        return false;
+    }
+    return 1 === preg_match(TAG_RE, $tag);
+}
+
+/**
+ * `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+ * tag ''.
+ *
+ * @param mixed $str
+ * @return array{name:string,tag:string}
+ */
+function parse_ref($str): array
+{
+    if (!is_string($str)) {
+        fail_with('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 (§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.
+    $cut = strpos($str, '$');
+    $name = false === $cut ? $str : substr($str, 0, $cut);
+    $tag = false === $cut ? '' : substr($str, $cut + 1);
+
+    if (!check_name($name)) {
+        fail_with('plugin_bad_name', 'invalid plugin name: ' . $name,
+                  ['name' => $name]);
+    }
+    if (!check_tag($tag)) {
+        fail_with('plugin_bad_tag', 'invalid plugin tag: ' . $tag,
+                  ['name' => $name, 'tag' => $tag]);
+    }
+
+    return ['name' => $name, 'tag' => $tag];
+}
+
+/**
+ * The pair -> `name$tag`. An empty tag NEVER writes the separator, which
+ * is the half of canonicalization format_ref owns: parse tolerates
+ * `stripe$`, format never produces it, so a round trip is idempotent.
+ *
+ * @param mixed $name
+ * @param mixed $tag
+ */
+function format_ref($name, $tag = null): string
+{
+    $tag = null === $tag ? '' : $tag;
+    if (!check_name($name)) {
+        fail_with('plugin_bad_name',
+                  'invalid plugin name: ' . Util::json($name),
+                  ['name' => $name]);
+    }
+    if (!check_tag($tag)) {
+        fail_with('plugin_bad_tag', 'invalid plugin tag: ' . Util::json($tag),
+                  ['name' => $name, 'tag' => $tag]);
+    }
+    return '' === $tag ? $name : $name . '$' . $tag;
+}
+
+/**
+ * The canonical spelling of a ref. §4 rule 5: ports must canonicalize
+ * before comparison.
+ *
+ * @param mixed $str
+ */
+function canon_ref($str): string
+{
+    $r = parse_ref($str);
+    return format_ref($r['name'], $r['tag']);
+}
+
+/**
+ * canon_ref 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.
+ *
+ * @param mixed $str
+ * @return mixed
+ */
+function canon($str)
+{
+    try {
+        return canon_ref($str);
+    } catch (PluginError $e) {
+        return $str;
+    }
+}
+
+/**
+ * @param mixed $str
+ * @return mixed
+ */
+function refname($str)
+{
+    try {
+        return parse_ref($str)['name'];
+    } catch (PluginError $e) {
+        return $str;
+    }
+}

package/project/.sdk/tm/php/feature/secrets/plugin/Resolve.php

@@ -0,0 +1,79 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Resolve.php)
+// 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.
+
+/**
+ * Dynamic resolution (§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 §15.4 puts real module loading in per-port integration tests rather
+ * than here.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+const DEFAULT_SOURCES = [
+    ['kind' => 'module',
+     'prefix' => ['@voxgig/plugin-', 'voxgig-plugin-', 'plugin-', '']],
+];
+
+/**
+ * @param mixed $sources
+ * @return string[]
+ */
+function resolve_candidates(string $name, $sources = null): array
+{
+    $out = [];
+
+    // 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 (str_starts_with($name, '@')) {
+        return [$name];
+    }
+
+    $list = (null === $sources || [] === $sources) ? DEFAULT_SOURCES : $sources;
+
+    foreach ($list as $src) {
+        $kind = $src['kind'] ?? null;
+        if ('module' === $kind) {
+            $prefixes = $src['prefix'] ?? null;
+            if (null === $prefixes || [] === $prefixes) {
+                $prefixes = [''];
+            }
+            foreach ($prefixes as $p) {
+                $id = $p . $name;
+                if (!in_array($id, $out, true)) {
+                    $out[] = $id;
+                }
+            }
+        } elseif ('path' === $kind) {
+            $id = preg_replace('/\/+\z/', '', (string)($src['dir'] ?? '')) . '/' . $name;
+            if (!in_array($id, $out, true)) {
+                $out[] = $id;
+            }
+        }
+    }
+
+    return $out;
+}
+
+/**
+ * A MODULE PATH IS NOT A NAME (§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.
+ *
+ * @param mixed $from
+ * @return array<int,mixed>
+ */
+function resolve_from($from): array
+{
+    return [$from];
+}