@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/resolve.ex

@@ -0,0 +1,59 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/resolve.ex)
+# 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.
+defmodule Voxgig.Plugin.Resolve do
+  @moduledoc """
+  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.
+  """
+
+  alias Voxgig.Plugin.Types
+
+  def default_sources do
+    [%{"kind" => "module",
+       "prefix" => ["@voxgig/plugin-", "voxgig-plugin-", "plugin-", ""]}]
+  end
+
+  def resolve_candidates(name, sources) do
+    # 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 String.starts_with?(name, "@") do
+      [name]
+    else
+      list = if is_list(sources) and [] != sources, do: sources, else: default_sources()
+
+      list
+      |> Enum.flat_map(fn src ->
+        case Types.get(src, "kind") do
+          "module" ->
+            prefixes = Types.get(src, "prefix")
+            prefixes = if is_list(prefixes) and [] != prefixes, do: prefixes, else: [""]
+            Enum.map(prefixes, &(&1 <> name))
+
+          "path" ->
+            dir = String.replace(Types.get(src, "dir") || "", ~r{/+\z}, "")
+            [dir <> "/" <> name]
+
+          _ ->
+            []
+        end
+      end)
+      |> Enum.uniq()
+    end
+  end
+
+  @doc """
+  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.
+  """
+  def resolve_from(from), do: [from]
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/types.ex

@@ -0,0 +1,190 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/types.ex)
+# 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.
+defmodule Voxgig.Plugin.Types do
+  @moduledoc """
+  Shared types and the value helpers every module reads data through.
+
+  Deliberately small: the design's section 19 budget says the library owns
+  naming, configuration, lifecycle, ordering, binding and teardown, and
+  nothing else.
+
+  ELIXIR IS THE FIRST PORT THAT NEEDS NO TRICKS FOR THE VALUE MODEL, and
+  it is worth saying which tricks it does without:
+
+    * `%{}` and `[]` are DIFFERENT TYPES, so the empty-map-versus-empty-list
+      distinction php cannot draw and lua needs tagged tables for is free
+      here.
+    * A map holds `nil`, so `Map.has_key?` separates ABSENT from
+      present-and-null with no sentinel - perl and lua both carry one.
+    * `1 == 1.0` is true and `true == 1`, `"1" == 1` are both false, which
+      is exactly JSON's one number type plus JSON's type-strict equality.
+      php, perl and lua each need a guard for that; ruby, rust, java and
+      this port do not.
+
+  What it does NOT give free is mutation, and `Voxgig.Plugin.Host` says
+  what that cost.
+  """
+
+  @doc "Section 5.1's seven statuses, and no more."
+  def statuses, do: ~w(declared loaded pending live failed loading closing)
+
+  @doc """
+  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.
+  """
+  def detail_order do
+    ~w(host ref name tag point key capability range version match
+       candidates cycle holders refs path cause)
+  end
+
+  @doc "The value at a key, or nil. Absence and null read the same here."
+  def get(map, key) when is_map(map), do: Map.get(map, key)
+  def get(_, _), do: nil
+
+  @doc "PRESENCE, which is what distinguishes an authored null from absence."
+  def has(map, key) when is_map(map), do: Map.has_key?(map, key)
+  def has(_, _), do: false
+
+  def at(list, index) when is_list(list), do: Enum.at(list, index)
+  def at(_, _), do: nil
+
+  @doc "The keys of a map, SORTED - every walk of a map goes through here."
+  def keys(map) when is_map(map), do: map |> Map.keys() |> Enum.sort()
+  def keys(_), do: []
+
+  @doc """
+  Ruby's truthiness, which is not elixir's: present, and not `false`. `0`
+  and `""` are values the corpus distinguishes from absence, and elixir
+  already agrees about those two - only `nil` and `false` are falsy.
+  """
+  def truthy(value), do: not (is_nil(value) or false == value)
+
+  @doc """
+  An INTEGER, and only when the value is one. Section 7's band is an
+  integer the document wrote as one; `true` and `"2"` are not bands.
+  """
+  def asint(value) when is_integer(value), do: value
+  def asint(value) when is_float(value) do
+    if value == Float.floor(value), do: trunc(value), else: nil
+  end
+  def asint(_), do: nil
+
+  @doc """
+  A STABLE sort by a key function.
+
+  Stability is load-bearing, not tidiness: the canonical's comparators fall
+  through to a `pos` or ref tie-break that javascript's stable sort then
+  resolves by POSITION, and a port that shuffled equal keys would order a
+  teardown differently between two runs of the same process. Replacing this
+  with an unstable sort fails `order/order/seqtie`.
+
+  `Enum.sort_by/2` is already that sort. Its documented promise is
+  conditional - `Enum.sort/2` is "stable as long as the given function
+  returns true for equal terms" - and the `<=` comparator `sort_by/2`
+  builds from a key function is exactly one that does. THE NAME IS WHAT
+  THIS FUNCTION IS FOR: every sort in the port goes through one place that
+  says stability is required, so the next reader does not have to re-derive
+  that conditional from the docs.
+  """
+  def stable_sort_by(list, keyfun), do: Enum.sort_by(list, keyfun)
+
+  @doc """
+  JSON equality: same type, then same value.
+
+  `==` is exactly right here: it reads `1 == 1.0` as true (JSON has one
+  number type) and `true == 1`, `"1" == 1` as false (JSON is type-strict).
+  Map and list comparison is structural and key order does not matter,
+  which is what the corpus asserts.
+  """
+  def same(a, b), do: a == b
+
+  @doc """
+  `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.
+  """
+  def formaterror(code, text, details) do
+    parts =
+      detail_order()
+      |> Enum.filter(&has(details, &1))
+      |> Enum.map(fn k -> "#{k}=#{encode(Map.get(details, k))}" end)
+
+    tail = if [] == parts, do: "", else: " [" <> Enum.join(parts, " ") <> "]"
+    "plugin/#{code}: #{text}#{tail}"
+  end
+
+  @doc "Throw a section 12 error. One spelling, so every raise site reads the same."
+  def fail(code, text, details \\ %{}) do
+    raise Voxgig.Plugin.Error,
+      code: code,
+      text: text,
+      details: details,
+      message: formaterror(code, text, details)
+  end
+
+  @doc """
+  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.
+  """
+  def codeof(%Voxgig.Plugin.Error{code: code}), do: code
+  def codeof(_), do: ""
+
+  def message(%Voxgig.Plugin.Error{message: message}), do: message
+  def message(error) when is_exception(error), do: Exception.message(error)
+  def message(other), do: inspect(other)
+
+  @doc """
+  Compact JSON, map keys in sorted order.
+
+  Written here rather than in `Json` so that `formaterror` - which every
+  module reaches - does not pull the parser in behind it.
+  """
+  def encode(nil), do: "null"
+  def encode(true), do: "true"
+  def encode(false), do: "false"
+
+  def encode(value) when is_integer(value), do: Integer.to_string(value)
+
+  def encode(value) when is_float(value) do
+    # An integral float prints without a fractional part, so a `pos` of 3
+    # renders as `3` and not `3.0` - JSON has one number type and the
+    # corpus writes them as it means them.
+    if value == Float.floor(value) and abs(value) < 1.0e15 do
+      Integer.to_string(trunc(value))
+    else
+      Float.to_string(value)
+    end
+  end
+
+  def encode(value) when is_binary(value) do
+    escaped =
+      value
+      |> String.replace("\\", "\\\\")
+      |> String.replace("\"", "\\\"")
+      |> String.replace("\n", "\\n")
+      |> String.replace("\r", "\\r")
+      |> String.replace("\t", "\\t")
+
+    "\"" <> escaped <> "\""
+  end
+
+  def encode(value) when is_list(value) do
+    "[" <> Enum.map_join(value, ",", &encode/1) <> "]"
+  end
+
+  def encode(value) when is_map(value) and not is_struct(value) do
+    "{" <> Enum.map_join(keys(value), ",", fn k -> encode(k) <> ":" <> encode(Map.get(value, k)) end) <> "}"
+  end
+
+  # A host object published through `exports` (section 11) - the library
+  # never inspects one and nothing in the corpus compares one.
+  def encode(_), do: "\"(opaque)\""
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/version.ex

@@ -0,0 +1,136 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/version.ex)
+# 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.
+defmodule Voxgig.Plugin.Version do
+  @moduledoc """
+  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.
+  """
+
+  alias Voxgig.Plugin.Types
+
+  @doc """
+  A COMPONENT IS BOUNDED, and the bound is the model's, not the host
+  language's. Elixir's integers are unbounded and JavaScript's numbers stop
+  being exact past 2**53, so a twenty-digit component 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.
+  """
+  def component_max, do: 2_147_483_647
+
+  defp component(digits, whole, field) do
+    value = String.to_integer(digits)
+
+    if component_max() < value do
+      Types.fail("plugin_bad_range",
+                 "version component out of range in #{whole}: #{digits}",
+                 %{field => whole})
+    end
+
+    value
+  end
+
+  # `1`, `1.2` or `1.2.3`, fully anchored.
+  defp parts(text, whole, field) do
+    pieces = String.split(text, ".")
+
+    cond do
+      3 < length(pieces) ->
+        nil
+
+      Enum.any?(pieces, fn p -> "" == p or not String.match?(p, ~r/\A[0-9]+\z/) end) ->
+        nil
+
+      true ->
+        parsed = Enum.map(pieces, &component(&1, whole, field))
+        parsed ++ List.duplicate(0, 3 - length(parsed))
+    end
+  end
+
+  @doc """
+  Two forms and no more (section 11.2): `'2.1'` is >= 2.1.0 and < 3.0.0;
+  `'~2.1'` is >= 2.1.0 and < 2.2.0.
+  """
+  def parse_range(range) when is_binary(range) and range != "" do
+    tilde = String.starts_with?(range, "~")
+    body = if tilde, do: String.slice(range, 1..-1//1), else: range
+
+    case parts(body, range, "range") do
+      nil ->
+        Types.fail("plugin_bad_range", "invalid range: #{range}", %{"range" => range})
+
+      [major, minor, patch] ->
+        hi = if tilde, do: [major, minor + 1, 0], else: [major + 1, 0, 0]
+        %{"lo" => [major, minor, patch], "hi" => hi}
+    end
+  end
+
+  def parse_range(range) do
+    Types.fail("plugin_bad_range", "invalid range: #{Types.encode(range)}", %{"range" => range})
+  end
+
+  def parse_version(version) when is_binary(version) do
+    case parts(version, version, "version") do
+      nil ->
+        Types.fail("plugin_bad_range", "invalid version: #{version}", %{"version" => version})
+
+      triple ->
+        triple
+    end
+  end
+
+  def parse_version(version) do
+    Types.fail("plugin_bad_range", "invalid version: #{Types.encode(version)}",
+               %{"version" => version})
+  end
+
+  @doc "The one satisfaction predicate: lo <= version < hi."
+  def satisfies(version, range) do
+    v = parse_version(version)
+    r = parse_range(range)
+    compare(v, r["lo"]) >= 0 and compare(v, r["hi"]) < 0
+  end
+
+  @doc """
+  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.
+  """
+  def satisfiesq(version, range) do
+    satisfies(version, range)
+  rescue
+    Voxgig.Plugin.Error -> false
+  end
+
+  defp compare([], []), do: 0
+  defp compare([a | as], [b | bs]) do
+    cond do
+      a < b -> -1
+      a > b -> 1
+      true -> compare(as, bs)
+    end
+  end
+
+  @doc "The version triple as a comparable key, for the capability rank."
+  def version_parts(text) do
+    text
+    |> to_string()
+    |> String.split(".")
+    |> Enum.map(fn p ->
+      case Integer.parse(p) do
+        {n, _} -> n
+        :error -> 0
+      end
+    end)
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/voxgig_plugin.ex

@@ -0,0 +1,42 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin.ex)
+# 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.
+defmodule Voxgig.Plugin do
+  @moduledoc """
+  The canonical surface `make parity` checks (AGENTS.md section 4). Small
+  on purpose (section 19): everything else is functions on `Host` and
+  `Inst`, because a library that grows a second public entry point per
+  feature is a library twenty ports pay for twice.
+
+  ELEVEN NAMES, AND THEY ARE DELEGATIONS RATHER THAN DEFINITIONS. The
+  implementation lives in the module named for its design section, so a
+  reader who arrives at `resolve_order/2` from the corpus lands in
+  `Voxgig.Plugin.Order` where section 7 is quoted, not in a facade that
+  forwards.
+  """
+
+  alias Voxgig.Plugin.Catalog
+  alias Voxgig.Plugin.Config
+  alias Voxgig.Plugin.Env
+  alias Voxgig.Plugin.Host
+  alias Voxgig.Plugin.Order
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Resolve
+
+  # host construction
+  defdelegate make_host(options \\ nil), to: Host
+  defdelegate make_catalog(definitions \\ nil), to: Catalog
+
+  # refs - the first thing a new port implements (section 4)
+  defdelegate parse_ref(str), to: Ref
+  defdelegate format_ref(name, tag), to: Ref
+  defdelegate check_name(name), to: Ref
+  defdelegate check_tag(tag), to: Ref
+
+  # pure functions over documents and definitions
+  defdelegate normalize_config(input), to: Config
+  defdelegate resolve_options(input), to: Config
+  defdelegate resolve_order(bindings, pin \\ nil), to: Order
+  defdelegate resolve_candidates(name, sources), to: Resolve
+  defdelegate apply_env(input), to: Env
+end