@voxgig/sdkgen 4.9.0 → 4.11.0

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin/Types.pm

@@ -0,0 +1,251 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Types.pm)
+# 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::Types;
+
+# Shared types. Deliberately small: the design's section 19 budget says
+# the library owns naming, configuration, lifecycle, ordering, binding and
+# teardown, and nothing else.
+#
+# PERL'S ONE STRUCTURAL HAZARD IS THAT IT HAS NO JSON TYPES. A scalar that
+# holds 1 and a scalar that holds "1" are the same thing to `==` and to
+# `eq`, and the corpus pins them as DIFFERENT (capability/match). So this
+# file carries `jsontype`, which reads the SV's own flags - the same test
+# JSON::PP uses to decide whether to emit a number - and every comparison
+# in the port goes through it.
+#
+# The second hazard is that a hash has NO ORDER, and a randomized one at
+# that. Every place the canonical iterates a map, this port sorts the keys
+# first; `sortstrings` is the one spelling of that.
+
+use strict;
+use warnings;
+use B ();
+use Scalar::Util qw(blessed reftype);
+use builtin qw(is_bool);
+no warnings 'experimental::builtin';
+
+use Exporter 'import';
+our @EXPORT_OK = qw(
+    fail_with codeof formaterror jsontype truthy ismap islist
+    sortstrings sortedkeys stable_sort_by clone_value
+    STATUSES DETAIL_ORDER
+);
+
+# Section 5.1's seven statuses, and no more. A port that adds an eighth is
+# diverging. `loading` and `closing` are observable only from inside a
+# callback or from another thread.
+our @STATUSES = qw(declared loaded pending live failed loading closing);
+
+# Section 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.
+our @DETAIL_ORDER = qw(
+    host ref name tag point key capability
+    range version match candidates cycle holders
+    refs path cause
+);
+
+# The JSON type of a value, read from the scalar itself.
+#
+# `is_bool` is 5.36's, and it is the only reason this port can tell `true`
+# from `1` at all - perl's own booleans ARE 1 and "", and nothing else in
+# the language distinguishes them. The corpus runner converts JSON::PP's
+# blessed booleans to native ones on the way in, so both spellings answer
+# 'bool' here.
+#
+# THE NUMBER TEST HAS A KNOWN LIMIT, and it is perl's rather than this
+# port's: using a numeric scalar in STRING context sets its POK flag
+# permanently, after which it reads as a string. JSON::PP's encoder has
+# exactly the same limit for exactly the same reason. Nothing in this port
+# interpolates a corpus value before comparing it, and `same` would report
+# a loud disagreement rather than a quiet pass if something ever did.
+sub jsontype {
+    my ($v) = @_;
+    return 'null' if !defined $v;
+    my $r = ref $v;
+    if ($r) {
+        return 'list' if 'ARRAY' eq $r;
+        return 'map'  if 'HASH' eq $r;
+        return 'bool' if 'JSON::PP::Boolean' eq $r;
+        return 'code' if 'CODE' eq $r;
+        return 'object';
+    }
+    return 'bool' if is_bool($v);
+    my $flags = B::svref_2object(\$v)->FLAGS;
+    return 'num'
+        if ($flags & (B::SVp_IOK() | B::SVp_NOK()))
+        && !($flags & B::SVp_POK());
+    return 'str';
+}
+
+sub ismap  { 'HASH' eq (ref($_[0]) // '') }
+sub islist { 'ARRAY' eq (ref($_[0]) // '') }
+
+# Ruby's truthiness, which is not perl's: `0`, `""` and an empty list are
+# all values the corpus distinguishes from absence. A transcribed
+# truthiness test says what it means here - present, and not false.
+sub truthy {
+    my ($v) = @_;
+    return 0 if !defined $v;
+    return $v ? 1 : 0 if 'bool' eq jsontype($v);
+    return 1;
+}
+
+# Byte-wise. `sort` with no comparator is already `cmp`, but saying it
+# leaves no doubt that this is not a locale or a numeric sort.
+sub sortstrings { return sort { $a cmp $b } @_ }
+
+sub sortedkeys { my ($h) = @_; return sort { $a cmp $b } keys %$h }
+
+# STABLE sort by a computed key list. `use sort 'stable'` is on in every
+# file that sorts, so this is a comparator rather than a decoration - but
+# the COMPARISON is still the port's own, because the canonical's rank
+# falls through tiers of mixed numbers and strings.
+sub stable_sort_by {
+    my ($list, $keyof) = @_;
+    my @out = sort { cmpkey($keyof->($a), $keyof->($b)) } @$list;
+    return \@out;
+}
+
+# Compare two key lists part by part. Numbers compare numerically, strings
+# byte-wise, and a nested list recurses - which is what the capability rank
+# needs for its version triple.
+sub cmpkey {
+    # NOT `my ($a, $b)`: `$a` and `$b` are the sort globals, and shadowing
+    # them inside a routine a sort block calls is the classic way to make a
+    # comparator quietly compare nothing.
+    my ($ka, $kb) = @_;
+    my $n = @$ka > @$kb ? scalar @$ka : scalar @$kb;
+    for my $i (0 .. $n - 1) {
+        my $x = $i < @$ka ? $ka->[$i] : 0;
+        my $y = $i < @$kb ? $kb->[$i] : 0;
+        my $c;
+        if (islist($x) && islist($y)) {
+            $c = cmpkey($x, $y);
+        }
+        elsif ('str' eq jsontype($x) || 'str' eq jsontype($y)) {
+            $c = "$x" cmp "$y";
+        }
+        else {
+            $c = ($x // 0) <=> ($y // 0);
+        }
+        return $c if 0 != $c;
+    }
+    return 0;
+}
+
+sub clone_value {
+    my ($v) = @_;
+    return [ map { clone_value($_) } @$v ] if islist($v);
+    return { map { $_ => clone_value($v->{$_}) } keys %$v } if ismap($v);
+    return $v;
+}
+
+# `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.
+sub formaterror {
+    my ($code, $text, $details) = @_;
+    $details //= {};
+    my @parts;
+    for my $k (@DETAIL_ORDER) {
+        next if !exists $details->{$k};
+        push @parts, $k . '=' . _json($details->{$k});
+    }
+    my $tail = @parts ? ' [' . join(' ', @parts) . ']' : '';
+    return "plugin/$code: $text$tail";
+}
+
+# A local encoder rather than JSON::PP, because the library must not
+# depend on a module the port could be embedded without - and because the
+# only values it ever sees are error details.
+sub _json {
+    my ($v) = @_;
+    my $type = jsontype($v);
+    return 'null' if 'null' eq $type;
+    return $v ? 'true' : 'false' if 'bool' eq $type;
+    return "$v" if 'num' eq $type;
+    if ('list' eq $type) {
+        return '[' . join(',', map { _json($_) } @$v) . ']';
+    }
+    if ('map' eq $type) {
+        return '{' . join(',',
+            map { _json("$_") . ':' . _json($v->{$_}) } sortedkeys($v)) . '}';
+    }
+    my $s = "$v";
+    $s =~ s/(["\\])/\\$1/g;
+    $s =~ s/\n/\\n/g;
+    $s =~ s/\t/\\t/g;
+    $s =~ s/\r/\\r/g;
+    $s =~ s/\x08/\\b/g;
+    $s =~ s/\x0c/\\f/g;
+    # THE WHOLE CONTROL RANGE, not the five spellings with a short escape.
+    # A cause or detail carrying \x01 - which a foreign library's message
+    # can - emitted the raw byte inside quotes, and the message stopped
+    # being the parseable JSON section 12 pins it as.
+    $s =~ s/([\x00-\x1f])/sprintf('\\u%04x', ord($1))/ge;
+    return '"' . $s . '"';
+}
+
+# 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.
+{
+    package Voxgig::Plugin::Error;
+
+    use overload '""' => sub { $_[0]->{message} }, fallback => 1;
+
+    sub new {
+        my ($class, $code, $text, $details) = @_;
+        return bless {
+            code    => $code,
+            text    => $text,
+            details => $details // {},
+            message => Voxgig::Plugin::Types::formaterror($code, $text, $details),
+        }, $class;
+    }
+
+    sub code    { $_[0]->{code} }
+    sub message { $_[0]->{message} }
+}
+
+sub fail_with {
+    my ($code, $text, $details) = @_;
+    die Voxgig::Plugin::Error->new($code, $text, $details);
+}
+
+# The section 12 code of an error, 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.
+#
+# A DUCK-TYPED READ, not an isa check: section 12 identifies an error by
+# its code and not by its class, and a plugin raising its own coded object
+# keeps that code (Host::run reads this to decide whether to wrap).
+sub codeof {
+    my ($err) = @_;
+    return '' if !defined $err || !ref $err;
+
+    # `ref` ON A BLESSED REFERENCE RETURNS THE CLASS NAME, NOT 'HASH', so
+    # gating on `'HASH' eq ref` read only unblessed hashes and this
+    # library's own class - an isa check wearing a duck's hat, and the
+    # opposite of what the comment above claims. A plugin raising its own
+    # coded object had the code dropped and `Host::run` rewrote it to
+    # `plugin_<phase>_failed`. `reftype` is the flag `ref` masks.
+    my $code;
+    if (blessed($err) && $err->can('code')) {
+        $code = eval { $err->code };
+    } elsif ('HASH' eq (reftype($err) // '')) {
+        $code = $err->{code};
+    }
+    return defined $code && !ref $code ? "$code" : '';
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin/Version.pm

@@ -0,0 +1,122 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin/Version.pm)
+# 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::Version;
+
+# 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.
+
+use strict;
+use warnings;
+use Voxgig::Plugin::Types qw(fail_with jsontype);
+
+use Exporter 'import';
+our @EXPORT_OK = qw(parse_range parse_version satisfies satisfiesq version_cmp);
+
+our $VERSION_RE = qr/\A(\d+)(?:\.(\d+))?(?:\.(\d+))?\z/;
+
+# A COMPONENT IS BOUNDED, and the bound is the model's, not the host
+# language's. Perl's integers are 64-bit and JavaScript's stop being exact
+# past 2**53, so `9223372036854775808.0.0` parsed to one 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.
+our $COMPONENT_MAX = 2147483647;
+
+# `0 + $digits` promotes past the integer range into a float rather than
+# wrapping, so a twenty-digit component lands far above the bound and the
+# check fires on it. A LENGTH GUARD WOULD BE DEAD CODE.
+sub component {
+    my ($digits, $whole, $field) = @_;
+    my $value = 0 + $digits;
+    fail_with('plugin_bad_range',
+              "version component out of range in $whole: $digits",
+              { $field => $whole })
+        if $COMPONENT_MAX < $value;
+    return $value;
+}
+
+# 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
+sub parse_range {
+    my ($range) = @_;
+    if ('str' ne jsontype($range) || '' eq $range) {
+        my $shown = defined $range && !ref $range ? $range : '(not a range)';
+        fail_with('plugin_bad_range', "invalid range: $shown", { range => $range });
+    }
+
+    my $tilde = 0 == index($range, '~');
+    my $body = $tilde ? substr($range, 1) : $range;
+    my @m = $body =~ $VERSION_RE;
+    fail_with('plugin_bad_range', "invalid range: $range", { range => $range })
+        if !@m;
+
+    my $major = component($m[0], $range, 'range');
+    my $minor = defined $m[1] ? component($m[1], $range, 'range') : 0;
+    my $patch = defined $m[2] ? component($m[2], $range, 'range') : 0;
+
+    return {
+        lo => [ $major, $minor, $patch ],
+        hi => $tilde ? [ $major, $minor + 1, 0 ] : [ $major + 1, 0, 0 ],
+    };
+}
+
+sub parse_version {
+    my ($version) = @_;
+    if ('str' ne jsontype($version)) {
+        my $shown = defined $version && !ref $version ? $version : '(not a version)';
+        fail_with('plugin_bad_range', "invalid version: $shown",
+                  { version => $version });
+    }
+    my @m = $version =~ $VERSION_RE;
+    fail_with('plugin_bad_range', "invalid version: $version",
+              { version => $version })
+        if !@m;
+    return [
+        component($m[0], $version, 'version'),
+        defined $m[1] ? component($m[1], $version, 'version') : 0,
+        defined $m[2] ? component($m[2], $version, 'version') : 0,
+    ];
+}
+
+# The one satisfaction predicate: lo <= version < hi.
+sub satisfies {
+    my ($version, $range) = @_;
+    my $v = parse_version($version);
+    my $r = parse_range($range);
+    return version_cmp($v, $r->{lo}) >= 0 && version_cmp($v, $r->{hi}) < 0
+        ? !!1 : !!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.
+sub satisfiesq {
+    my ($version, $range) = @_;
+    my $ok = eval { satisfies($version, $range) };
+    return $ok ? 1 : 0;
+}
+
+sub version_cmp {
+    my ($x, $y) = @_;
+    for my $i (0 .. 2) {
+        my $l = $x->[$i] // 0;
+        my $r = $y->[$i] // 0;
+        return $l < $r ? -1 : 1 if $l != $r;
+    }
+    return 0;
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugin/Voxgig/Plugin.pm

@@ -0,0 +1,70 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (perl/lib/Voxgig/Plugin.pm)
+# 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 canonical surface `make parity` checks (AGENTS.md section 4). Small
+# on purpose (section 19): everything else is methods on the host and
+# instance types, because a library that grows a second public entry point
+# per feature is a library twenty ports pay for twice.
+#
+#   make_host  make_catalog
+#   parse_ref  format_ref  check_name  check_tag
+#   normalize_config  resolve_options  resolve_order  resolve_candidates
+#   apply_env
+#
+# One package per file, and this one ALIASES rather than re-implements: the
+# alias block is the surface, in one place, and a name that stops existing
+# stops existing here loudly.
+
+use strict;
+use warnings;
+
+use Voxgig::Plugin::Types;
+use Voxgig::Plugin::Ref;
+use Voxgig::Plugin::Version;
+use Voxgig::Plugin::Capability;
+use Voxgig::Plugin::Resolve;
+use Voxgig::Plugin::Graph;
+use Voxgig::Plugin::Order;
+use Voxgig::Plugin::Config;
+use Voxgig::Plugin::Env;
+use Voxgig::Plugin::Export;
+use Voxgig::Plugin::Point;
+use Voxgig::Plugin::Catalog;
+use Voxgig::Plugin::Depend;
+use Voxgig::Plugin::Host;
+
+use Exporter 'import';
+our @EXPORT_OK = qw(
+    make_host make_catalog
+    parse_ref format_ref check_name check_tag canon_ref
+    normalize_config resolve_options resolve_order resolve_candidates
+    resolve_from resolve_capability resolve_graph apply_env
+    parse_range satisfies codeof
+);
+
+# A glob assignment is a single mention of the name, which `use warnings`
+# reads as a probable typo. It is not: the alias IS the surface.
+no warnings 'once';
+
+*make_host          = \&Voxgig::Plugin::Host::make_host;
+*make_catalog       = \&Voxgig::Plugin::Catalog::make_catalog;
+*parse_ref          = \&Voxgig::Plugin::Ref::parse_ref;
+*format_ref         = \&Voxgig::Plugin::Ref::format_ref;
+*check_name         = \&Voxgig::Plugin::Ref::check_name;
+*check_tag          = \&Voxgig::Plugin::Ref::check_tag;
+*canon_ref          = \&Voxgig::Plugin::Ref::canon_ref;
+*normalize_config   = \&Voxgig::Plugin::Config::normalize_config;
+*resolve_options    = \&Voxgig::Plugin::Config::resolve_options;
+*resolve_order      = \&Voxgig::Plugin::Order::resolve_order;
+*resolve_candidates = \&Voxgig::Plugin::Resolve::resolve_candidates;
+*resolve_from       = \&Voxgig::Plugin::Resolve::resolve_from;
+*resolve_capability = \&Voxgig::Plugin::Capability::resolve_capability;
+*resolve_graph      = \&Voxgig::Plugin::Graph::resolve_graph;
+*apply_env          = \&Voxgig::Plugin::Env::apply_env;
+*parse_range        = \&Voxgig::Plugin::Version::parse_range;
+*satisfies          = \&Voxgig::Plugin::Version::satisfies;
+*codeof             = \&Voxgig::Plugin::Types::codeof;
+
+1;