@voxgig/sdkgen 1.5.1 → 2.0.0

package/project/.sdk/tm/py-data/test/test_frames.py

@@ -0,0 +1,250 @@
+# ProjectName Data — frames engine tests.
+#
+# These cover the runtime that is the same for every API, so they live in the
+# template rather than being generated. The generated per-entity accessor
+# tests are in test_entity_frames.py.
+
+from __future__ import annotations
+
+import dataclasses
+
+import pandas as pd
+import pytest
+
+from projectname_data.frames import (
+    build_frame,
+    to_record,
+    to_records,
+    apply_dtypes,
+    apply_dates,
+    order_columns,
+    records_df,
+    to_series,
+)
+
+
+@dataclasses.dataclass
+class Sample:
+    name: str
+    count: int
+    nested: dict
+
+
+class FakeEntity:
+    """Stands in for a generated ProjectName<X>Entity.
+
+    The private attributes matter: an entity's record is NOT in its public
+    __dict__, so anything relying on attribute scraping returns {} here.
+    """
+
+    def __init__(self, rec):
+        self._name = "thing"
+        self._data = rec
+        self._client = object()
+
+    def data_get(self):
+        return dict(self._data)
+
+
+class TestToRecords:
+
+    def test_entity_object_is_unwrapped_via_data_get(self):
+        # list() yields entity OBJECTS, not dicts. Missing this produced a
+        # frame with the right row count and zero columns.
+        rec = to_record(FakeEntity({"id": "earth", "name": "Earth"}))
+        assert rec == {"id": "earth", "name": "Earth"}
+
+    def test_entities_build_a_populated_frame(self):
+        df = build_frame([
+            FakeEntity({"id": "earth", "diameter": 12756}),
+            FakeEntity({"id": "mars", "diameter": 6792}),
+        ])
+        assert df.shape == (2, 2)
+        assert list(df["id"]) == ["earth", "mars"]
+
+    def test_entity_wins_over_the_dunder_dict_fallback(self):
+        rec = to_record(FakeEntity({"id": "x"}))
+        assert "_data" not in rec
+        assert rec != {}
+
+    def test_dataclass_becomes_dict(self):
+        rec = to_record(Sample(name="a", count=1, nested={"x": 2}))
+        assert rec == {"name": "a", "count": 1, "nested": {"x": 2}}
+
+    def test_dict_passes_through(self):
+        assert to_record({"a": 1}) == {"a": 1}
+
+    def test_none_is_none(self):
+        assert to_record(None) is None
+
+    def test_single_record_is_wrapped(self):
+        assert to_records({"a": 1}) == [{"a": 1}]
+
+    def test_none_is_empty(self):
+        assert to_records(None) == []
+
+    def test_list_of_dataclasses(self):
+        out = to_records([Sample("a", 1, {}), Sample("b", 2, {})])
+        assert [r["name"] for r in out] == ["a", "b"]
+
+
+class TestFlatten:
+
+    def test_one_level_by_default(self):
+        df = build_frame([{"a": 1, "b": {"c": 2}}])
+        assert "b.c" in df.columns
+        assert "b" not in df.columns
+
+    def test_flatten_none_keeps_nesting(self):
+        df = build_frame([{"a": 1, "b": {"c": 2}}], flatten="none")
+        assert "b" in df.columns
+        assert df["b"].iloc[0] == {"c": 2}
+
+    def test_deep_nesting_stays_boxed_at_depth_one(self):
+        # The point of the depth-1 default: a deep payload must not explode
+        # into hundreds of columns.
+        df = build_frame([{"a": {"b": {"c": {"d": 1}}}}])
+        assert "a.b" in df.columns
+        assert isinstance(df["a.b"].iloc[0], dict)
+
+    def test_flatten_full_recurses(self):
+        df = build_frame([{"a": {"b": {"c": 1}}}], flatten="full")
+        assert "a.b.c" in df.columns
+
+
+class TestDtypes:
+
+    def test_nullable_integer_survives_nulls(self):
+        # The whole reason for Int64 over int64: a null in an integer column
+        # must not silently turn the column into float64.
+        df = build_frame(
+            [{"n": 1}, {"n": None}, {"n": 3}],
+            dtypes={"n": "Int64"},
+        )
+        assert str(df["n"].dtype) == "Int64"
+        assert df["n"].iloc[0] == 1
+        assert pd.isna(df["n"].iloc[1])
+
+    def test_nullable_boolean_survives_nulls(self):
+        df = build_frame(
+            [{"b": True}, {"b": None}],
+            dtypes={"b": "boolean"},
+        )
+        assert str(df["b"].dtype) == "boolean"
+
+    def test_string_dtype_applied(self):
+        df = build_frame([{"s": "x"}], dtypes={"s": "string"})
+        assert str(df["s"].dtype) == "string"
+
+    def test_numeric_strings_are_rescued(self):
+        df = build_frame([{"n": "1"}, {"n": "2"}], dtypes={"n": "Int64"})
+        assert str(df["n"].dtype) == "Int64"
+        assert df["n"].iloc[1] == 2
+
+    def test_unconvertible_column_is_left_alone_not_raised(self):
+        # An analyst with a usable frame and one object column is far better
+        # served than one holding an exception.
+        df = build_frame([{"n": "not-a-number"}], dtypes={"n": "Int64"})
+        assert len(df) == 1
+        # And the VALUE must survive. to_numeric(errors="coerce") would have
+        # turned it into NA — a silent data loss dressed up as a successful
+        # conversion. The rescue is only allowed when it is lossless.
+        assert df["n"].iloc[0] == "not-a-number"
+
+    def test_partially_numeric_column_is_not_coerced(self):
+        # One bad value must not blank out the rest of the column.
+        df = build_frame(
+            [{"n": "1"}, {"n": "oops"}, {"n": "3"}],
+            dtypes={"n": "Int64"},
+        )
+        assert list(df["n"]) == ["1", "oops", "3"]
+
+    def test_numeric_rescue_still_applies_when_lossless(self):
+        # Nulls are not "lost" data, so a column of numeric strings with a
+        # None in it still converts.
+        df = build_frame(
+            [{"n": "1"}, {"n": None}, {"n": "3"}],
+            dtypes={"n": "Int64"},
+        )
+        assert str(df["n"].dtype) == "Int64"
+        assert df["n"].iloc[0] == 1
+        assert pd.isna(df["n"].iloc[1])
+
+    def test_missing_declared_column_is_ignored(self):
+        df = build_frame([{"a": 1}], dtypes={"absent": "Int64"})
+        assert "absent" not in df.columns
+
+    def test_dtype_false_skips_coercion(self):
+        df = build_frame([{"n": 1}], dtypes={"n": "string"}, dtype=False)
+        assert str(df["n"].dtype) != "string"
+
+
+class TestOrder:
+
+    def test_declared_order_first_extras_appended(self):
+        df = build_frame(
+            [{"z": 1, "a": 2, "extra": 3}],
+            order=["a", "z"],
+        )
+        assert list(df.columns) == ["a", "z", "extra"]
+
+    def test_absent_declared_columns_are_skipped(self):
+        df = order_columns(pd.DataFrame({"a": [1]}), ["missing", "a"])
+        assert list(df.columns) == ["a"]
+
+
+class TestEmpty:
+
+    def test_empty_result_keeps_columns_and_dtypes(self):
+        # A bare pd.DataFrame() would KeyError on the first column access;
+        # downstream code must behave the same whether or not rows came back.
+        df = build_frame([], order=["a", "b"], dtypes={"a": "Int64", "b": "string"})
+        assert list(df.columns) == ["a", "b"]
+        assert str(df["a"].dtype) == "Int64"
+        assert len(df) == 0
+        assert df.empty
+
+    def test_empty_without_model_is_still_a_frame(self):
+        df = build_frame([])
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 0
+
+
+class TestDates:
+
+    def test_parse_dates_is_explicit_and_utc(self):
+        df = build_frame([{"when": "2026-01-02T03:04:05Z"}], parse_dates=["when"])
+        assert str(df["when"].dtype).startswith("datetime64")
+        assert df["when"].iloc[0].year == 2026
+
+    def test_unparseable_date_becomes_nat_not_an_error(self):
+        df = build_frame([{"when": "nonsense"}], parse_dates=["when"])
+        assert pd.isna(df["when"].iloc[0])
+
+    def test_dates_are_never_inferred(self):
+        # No $DATE sentinel exists in the model, so a date-looking string must
+        # stay a string unless the caller asks for parsing.
+        df = build_frame([{"when": "2026-01-02T03:04:05Z"}])
+        assert not str(df["when"].dtype).startswith("datetime64")
+
+
+class TestScalarsAndSeries:
+
+    def test_scalar_list_becomes_value_column(self):
+        df = build_frame(["a", "b"])
+        assert list(df.columns) == ["value"]
+        assert list(df["value"]) == ["a", "b"]
+
+    def test_to_series_from_one_record(self):
+        s = to_series({"a": 1, "b": 2})
+        assert isinstance(s, pd.Series)
+        assert s["a"] == 1
+
+    def test_to_series_empty(self):
+        s = to_series(None)
+        assert isinstance(s, pd.Series)
+        assert len(s) == 0
+
+    def test_records_df_is_the_public_escape_hatch(self):
+        df = records_df([{"a": 1}])
+        assert list(df.columns) == ["a"]

package/project/.sdk/tm/rb/core/utility_type.rb

@@ -7,6 +7,7 @@ class ProjectNameUtility
                 :make_point, :make_spec, :make_url, :param, :prepare_auth,
                 :prepare_body, :prepare_headers, :prepare_method,
                 :prepare_params, :prepare_path, :prepare_query,
+                :graphql_body, :graphql_errors,
                 :result_basic, :result_body, :result_headers,
                 :transform_request, :transform_response, :custom
 

package/project/.sdk/tm/rb/feature/paging_feature.rb

@@ -45,6 +45,14 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
       paging = ctx.ctrl.paging
     end
 
+    # GraphQL paginates through operation VARIABLES, not the query string.
+    # This hook runs after make_spec, so spec.body already holds the
+    # { query, variables } envelope, and before make_fetch_def serialises it.
+    if "graphql" == VoxgigStruct.getprop(ctx.point, "kind")
+      _graphql_pre_request(ctx, paging)
+      return
+    end
+
     if !paging["cursor"].nil?
       spec.query[cursor_param] = paging["cursor"]
     elsif spec.query[page_param].nil?
@@ -57,6 +65,41 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
     end
   end
 
+  # Relay pagination: the cursor is the `after` variable (or whatever the
+  # model named it), and the page size is `first`.
+  def _graphql_pre_request(ctx, paging)
+    body = ctx.spec.body
+    return unless body.is_a?(Hash)
+
+    variables = body["variables"]
+    unless variables.is_a?(Hash)
+      variables = {}
+      body["variables"] = variables
+    end
+
+    after_var = @options["afterVar"] || "after"
+    first_var = @options["firstVar"] || "first"
+
+    # Only bind variables the operation actually declares, or the server
+    # rejects the document.
+    declared = {}
+    varlist = VoxgigStruct.getpath(ctx.point, "graphql.vars")
+    if varlist.is_a?(Array)
+      varlist.each do |v|
+        name = VoxgigStruct.getprop(v, "name")
+        declared[name] = true unless name.nil?
+      end
+    end
+
+    if !paging["cursor"].nil? && declared[after_var]
+      variables[after_var] = paging["cursor"]
+    end
+
+    if !@options["limit"].nil? && variables[first_var].nil? && declared[first_var]
+      variables[first_var] = @options["limit"]
+    end
+  end
+
   def PreResult(ctx)
     return unless @active
     return unless _list?(ctx)
@@ -75,6 +118,39 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
       "hasMore" => false,
     }
 
+    # Set when the response states hasMore outright, rather than leaving it
+    # to be inferred from the presence of a cursor.
+    explicit_more = false
+
+    # Relay connections carry the cursor in pageInfo, at the path the model
+    # recorded for this op.
+    page = VoxgigStruct.getpath(ctx.point, "graphql.page")
+    if page.is_a?(Hash) && body.is_a?(Hash)
+      # `connpath` locates the connection object inside the response envelope
+      # (data.<field>); the cursor/more paths are relative to it.
+      connpath = page["connpath"]
+      conn = body
+      if connpath.is_a?(String) && "" != connpath
+        sub = VoxgigStruct.getpath(body, connpath)
+        conn = sub unless sub.nil?
+      end
+
+      cursorpath = page["cursor"]
+      if cursorpath.is_a?(String) && "" != cursorpath
+        cursor = VoxgigStruct.getpath(conn, cursorpath)
+        paging["cursor"] = cursor unless cursor.nil?
+      end
+
+      morepath = page["more"]
+      if morepath.is_a?(String) && "" != morepath
+        more = VoxgigStruct.getpath(conn, morepath)
+        if more == true || more == false
+          paging["hasMore"] = more
+          explicit_more = true
+        end
+      end
+    end
+
     # Link: <...>; rel="next"
     link = _header(headers, "link")
     unless link.nil?
@@ -87,11 +163,21 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
       paging["next"] = paging["next"] || body["next"] unless body["next"].nil?
       paging["cursor"] = body["cursor"] unless body["cursor"].nil?
       paging["cursor"] = body["nextCursor"] unless body["nextCursor"].nil?
-      paging["hasMore"] = body["hasMore"] if body["hasMore"] == true || body["hasMore"] == false
+      if body["hasMore"] == true || body["hasMore"] == false
+        paging["hasMore"] = body["hasMore"]
+        explicit_more = true
+      end
     end
 
-    paging["hasMore"] = paging["hasMore"] ||
-      !paging["next"].nil? || !paging["cursor"].nil? || !paging["nextPage"].nil?
+    # Cursor presence only INFERS another page. When the server stated the
+    # answer outright — relay's `hasNextPage: false`, or a body `hasMore` —
+    # that wins: a final page normally carries both an end cursor and
+    # hasNextPage false, and inferring from the cursor there would send the
+    # caller back for a page that does not exist, forever.
+    unless explicit_more
+      paging["hasMore"] = paging["hasMore"] ||
+        !paging["next"].nil? || !paging["cursor"].nil? || !paging["nextPage"].nil?
+    end
 
     result.paging = paging
 

package/project/.sdk/tm/rb/utility/graphql.rb

@@ -0,0 +1,131 @@
+# ProjectName SDK utility: graphql
+#
+# GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
+# produces uses this file unchanged. The API-specific part — which
+# operations exist and what each one's document is — is model data,
+# computed once by apidef and emitted into Config.
+#
+# Two jobs:
+#
+#   GraphqlBody   — build { query, variables } for a point, binding the
+#                   op's arguments to the document's declared variables.
+#
+#   GraphqlErrors — lift a GraphQL failure into an SDK error. GraphQL
+#                   reports failures as a top-level `errors` array under
+#                   HTTP 200, so the status-driven path in result_basic
+#                   never sees them.
+
+require_relative 'struct/voxgig_struct'
+
+module ProjectNameUtilities
+  # Content type every GraphQL-over-HTTP request uses.
+  GRAPHQL_CONTENT_TYPE = 'application/json'
+
+  # Map a GraphQL error to the same error codes the HTTP path produces, so
+  # a caller handles auth or rate limiting identically on both transports.
+  # Servers put the machine-readable code in `extensions.code`;
+  # Linear-style APIs use `extensions.type`.
+  GraphqlErrorCode = ->(gqlerr) {
+    ext = VoxgigStruct.getprop(gqlerr, 'extensions') || {}
+
+    raw = VoxgigStruct.getprop(ext, 'code') ||
+          VoxgigStruct.getprop(ext, 'type') || ''
+    raw = raw.to_s.upcase
+
+    if raw.include?('AUTH') || raw.include?('FORBIDDEN') ||
+       raw.include?('UNAUTHENTICATED')
+      next 'request_auth'
+    end
+    if raw.include?('RATELIMIT') || raw.include?('RATE_LIMIT') ||
+       raw.include?('TOO_MANY')
+      next 'request_ratelimit'
+    end
+    if raw.include?('BAD_USER_INPUT') || raw.include?('VALIDATION') ||
+       raw.include?('INVALID')
+      next 'request_invalid'
+    end
+
+    'request_graphql'
+  }
+
+  # Build the request body for a GraphQL point.
+  #
+  # Variables come from the op's own arguments: a named variable binds to
+  # the like-named argument (`from`), and the input-object variable (empty
+  # `from`) takes the request data as a whole — which is what makes a
+  # generated create/update call look exactly like its REST equivalent.
+  GraphqlBody = ->(ctx) {
+    gql = VoxgigStruct.getprop(ctx.point, 'graphql')
+    next nil unless gql.is_a?(Hash)
+
+    # reqmatch/reqdata hold the caller's arguments for THIS call; data/match
+    # hold the entity's current state. Which pair depends on whether the op
+    # takes match or data input. A named variable falls back to the current
+    # state, so updating a loaded entity with just {title} still binds the
+    # stored id the mutation requires.
+    datainput = ctx.op && 'data' == ctx.op.input
+    reqsrc = datainput ? ctx.reqdata : ctx.reqmatch
+    datasrc = datainput ? ctx.data : ctx.match
+    reqsrc = {} unless reqsrc.is_a?(Hash)
+    datasrc = {} unless datasrc.is_a?(Hash)
+
+    variables = {}
+
+    varlist = VoxgigStruct.getprop(gql, 'vars')
+    varlist = [] unless varlist.is_a?(Array)
+
+    varlist.each do |spec|
+      next unless spec.is_a?(Hash)
+
+      name = VoxgigStruct.getprop(spec, 'name')
+      from = VoxgigStruct.getprop(spec, 'from')
+
+      if from.nil? || '' == from
+        # The input object IS the request body. Strip the action selector,
+        # which is an SDK-side point discriminator, not an API field.
+        body = {}
+        reqsrc.each { |k, v| body[k] = v unless '$action' == k }
+        variables[name] = body
+        next
+      end
+
+      # Only send variables the caller actually supplied: sending an
+      # explicit null would clear a field on many APIs.
+      val = VoxgigStruct.getprop(reqsrc, from)
+      val = VoxgigStruct.getprop(datasrc, from) if val.nil?
+      variables[name] = val unless val.nil?
+    end
+
+    {
+      'query' => VoxgigStruct.getprop(gql, 'doc'),
+      'variables' => variables
+    }
+  }
+
+  # Inspect a decoded GraphQL response body and record a failure when the
+  # server reported one. Returns true when an error was recorded.
+  #
+  # Partial data (`data` alongside `errors`) is treated as failure: the
+  # REST surface has no partial-success concept, and silently returning
+  # half an object would be worse than failing. The raw envelope stays
+  # available on the result for callers that need it.
+  GraphqlErrors = ->(ctx) {
+    result = ctx.result
+    point = ctx.point
+
+    next false if result.nil? || point.nil?
+    next false unless 'graphql' == VoxgigStruct.getprop(point, 'kind')
+
+    errors = VoxgigStruct.getprop(result.body, 'errors')
+    next false unless errors.is_a?(Array) && !errors.empty?
+
+    first = errors[0]
+    msg = VoxgigStruct.getprop(first, 'message') || 'graphql error'
+    msg = msg + ' (+' + (errors.length - 1).to_s + ' more)' if 1 < errors.length
+
+    result.err = ctx.make_error(GraphqlErrorCode.call(first), 'graphql: ' + msg)
+    result.ok = false
+
+    true
+  }
+end

package/project/.sdk/tm/rb/utility/make_options.rb

@@ -44,7 +44,7 @@ module ProjectNameUtilities
       "headers" => { "`$CHILD`" => "`$STRING`" },
       "allow" => {
         "method" => "GET,PUT,POST,PATCH,DELETE,OPTIONS",
-        "op" => "create,update,load,list,remove,command,direct",
+        "op" => "create,update,load,list,remove,command,direct,graphql",
       },
       "entity" => { "`$CHILD`" => { "`$OPEN`" => true, "active" => false, "alias" => {} } },
       "feature" => { "`$CHILD`" => { "`$OPEN`" => true, "active" => false } },

package/project/.sdk/tm/rb/utility/make_response.rb

@@ -15,6 +15,12 @@ module ProjectNameUtilities
     utility.result_basic.call(ctx)
     utility.result_headers.call(ctx)
     utility.result_body.call(ctx)
+
+    # GraphQL reports failures as a top-level `errors` array under HTTP
+    # 200, so result_basic's status check never sees them. Lift them here,
+    # before the response transform tries to unwrap data that is not there.
+    utility.graphql_errors.call(ctx)
+
     utility.transform_response.call(ctx)
 
     result.ok = true if result.err.nil?

package/project/.sdk/tm/rb/utility/make_spec.rb

@@ -1,5 +1,6 @@
 # ProjectName SDK utility: make_spec
 require_relative 'struct/voxgig_struct'
+require_relative 'graphql'
 require_relative '../core/spec'
 module ProjectNameUtilities
   MakeSpec = ->(ctx) {
@@ -36,8 +37,23 @@ module ProjectNameUtilities
     ctx.spec.params = utility.prepare_params.call(ctx)
     ctx.spec.query = utility.prepare_query.call(ctx)
     ctx.spec.headers = utility.prepare_headers.call(ctx)
-    ctx.spec.body = utility.prepare_body.call(ctx)
-    ctx.spec.path = utility.prepare_path.call(ctx)
+
+    if 'graphql' == VoxgigStruct.getprop(point, 'kind')
+      # GraphQL addresses one endpoint: no path parts, no query string, and
+      # the body carries the operation. prepare_body is skipped
+      # deliberately — it only emits a body for data-input ops, whereas
+      # every GraphQL op posts one, including load/list/remove.
+      ctx.spec.body = utility.graphql_body.call(ctx)
+      ctx.spec.path = ''
+      # prepare_query already copied the op's match arguments into the
+      # query string. Those same values are bound as operation variables,
+      # so leaving them would send /graphql?id=i1.
+      ctx.spec.query = {}
+      ctx.spec.headers['content-type'] = GRAPHQL_CONTENT_TYPE
+    else
+      ctx.spec.body = utility.prepare_body.call(ctx)
+      ctx.spec.path = utility.prepare_path.call(ctx)
+    end
 
     ctx.ctrl.explain["spec"] = ctx.spec if ctx.ctrl.explain
 

package/project/.sdk/tm/rb/utility/register.rb

@@ -24,6 +24,7 @@ require_relative 'prepare_method'
 require_relative 'prepare_params'
 require_relative 'prepare_path'
 require_relative 'prepare_query'
+require_relative 'graphql'
 require_relative 'result_basic'
 require_relative 'result_body'
 require_relative 'result_headers'
@@ -55,6 +56,8 @@ ProjectNameUtility.registrar = ->(u) {
   u.prepare_params = ProjectNameUtilities::PrepareParams
   u.prepare_path = ProjectNameUtilities::PreparePath
   u.prepare_query = ProjectNameUtilities::PrepareQuery
+  u.graphql_body = ProjectNameUtilities::GraphqlBody
+  u.graphql_errors = ProjectNameUtilities::GraphqlErrors
   u.result_basic = ProjectNameUtilities::ResultBasic
   u.result_body = ProjectNameUtilities::ResultBody
   u.result_headers = ProjectNameUtilities::ResultHeaders