@reventlessdev/reventless-spec 3.0.0-alpha.117 → 3.0.0-alpha.119

package/src/components/TaggedUnion.res

@@ -0,0 +1,238 @@
+/**
+A variant used as a **field** of a queryable's state — one fact with several
+shapes, rather than several fields that have to be kept in step by hand.
+
+```rescript
+@schema
+type geolocation =
+  | Pending({requestedFor: string})
+  | Located({point: Reventless.GeoPoint.t})
+  | Unresolvable({reason: string})
+```
+
+The value is stored the way sury encodes it — `{"TAG":"Located","point":{…}}` —
+and reaches GraphQL as a union of one object type per arm. Both halves need the
+*same* name for the union, and neither can derive it from the other: the SDL
+emitter walks a schema it reaches through a field path, and the write path has
+only the schema in hand. So the name is carried **on the schema**, set once at
+the declaration by `named` — the ppx does it for a variant a state record uses,
+and a framework type carrying a union does it beside its `Semantic.mark`.
+
+A union with no name is not emitted as one. It falls through to the IR's
+`Unknown`, which is a `String` in the SDL — the behaviour that predates this
+module — except that it is now reported at deploy time instead of silently.
+*/
+let unionNameId: S.Metadata.Id.t<string> = S.Metadata.Id.make(
+  ~namespace="reventless",
+  ~name="taggedUnionName",
+)
+
+/**
+Names a union, so that the type emitted for it and the `__typename` stamped into
+every stored value of it agree.
+
+Written at the declaration, never at the field: two fields holding the same union
+hold the same type, and naming it per field is what produces one GraphQL type per
+field path — the mistake `semanticCompositeNames` exists to undo for `Money`.
+*/
+let named = (~name: string, schema: S.t<'a>): S.t<'a> =>
+  schema->S.Metadata.set(~id=unionNameId, name)
+
+/**
+The name a union field's schema carries.
+
+Read straight off the field's schema, wrapper included: sury's `option` keeps the
+metadata of what it wraps, which matters because it does *not* keep the union as
+a nested schema — `option<t>` flattens the arms and the `undefined` into one
+`anyOf`, leaving nothing inside to consult. `TaggedUnionTest` pins that, since a
+sury release that stopped preserving it would turn every optional union field
+into a `String` with no compile error anywhere.
+*/
+let getName = (schema: S.t<unknown>): option<string> => S.Metadata.get(schema, ~id=unionNameId)
+
+/**
+The GraphQL type emitted for one arm: the union's name with the arm's own
+appended (`Geolocation` + `Located` = `GeolocationLocated`).
+
+One derivation, used by the SDL emitter and by the write-time stamp. A second
+spelling of this rule anywhere is a `__typename` that resolves to no member,
+which GraphQL reports as a null — and a null in a non-nullable field takes its
+parent with it.
+*/
+let memberTypeName = (~union: string, ~arm: string): string => union ++ arm
+
+/** The key a stored union value carries its member type under. */
+let typenameKey = "__typename"
+
+/** One arm: the constructor name sury writes into `TAG`, and the arm's schema. */
+type arm = {tag: string, schema: S.t<unknown>}
+
+// A payload sury named rather than the author: `| Located(GeoPoint.t)` encodes to
+// `{"TAG":"Located","_0":{…}}`, and `_0` would be published as an SDL field name
+// and as a stored key. The ppx refuses the shape at its declaration; this refuses
+// it again for a union declared where the ppx cannot see it, by declining to
+// classify the union at all.
+let isPositionalName = (name: string): bool =>
+  name->String.startsWith("_") &&
+  name->String.length > 1 &&
+  name
+  ->String.slice(~start=1, ~end=name->String.length)
+  ->String.split("")
+  ->Array.every(c => c >= "0" && c <= "9")
+
+/**
+The arms of a schema that is a union of tagged objects, or `None`.
+
+Refuses three shapes, all for reasons that are GraphQL's rather than sury's, and
+all of which encode and decode perfectly well:
+
+- a payload-less arm (`| Pending`), which sury writes as the bare string
+  `"Pending"` — a union member must be an object type;
+- an arm with no field of its own (`| Pending({})`), which would imply a member
+  type with zero fields;
+- a positional payload, whose field name is the compiler's `_0`.
+
+Declining leaves the field an `Unknown`, which is reported where it is emitted.
+*/
+let armsOf = (schema: S.t<unknown>): option<array<arm>> =>
+  switch schema {
+  | AnyOf({anyOf}) =>
+    let members = anyOf->Array.filter(v =>
+      switch v {
+      | Null(_) | Undefined(_) => false
+      | _ => true
+      }
+    )
+    if members->Array.length < 2 {
+      None
+    } else {
+      let arms = members->Array.filterMap(member =>
+        switch member {
+        | Object({properties}) =>
+          switch properties->Dict.get("TAG") {
+          | Some(String({const: ?Some(tag)})) =>
+            let fields = properties->Dict.toArray->Array.filter(((name, _)) => name !== "TAG")
+            if (
+              fields->Array.length == 0 ||
+                fields->Array.some(((name, _)) => isPositionalName(name))
+            ) {
+              None
+            } else {
+              Some({tag, schema: member})
+            }
+          | _ => None
+          }
+        | _ => None
+        }
+      )
+      arms->Array.length == members->Array.length ? Some(arms) : None
+    }
+  | _ => None
+  }
+
+/** A named union of tagged objects: its name and its arms, or `None`. */
+let classify = (schema: S.t<unknown>): option<(string, array<arm>)> =>
+  switch (getName(schema), armsOf(schema)) {
+  | (Some(name), Some(arms)) => Some((name, arms))
+  | _ => None
+  }
+
+/**
+Whether a schema is a union of tagged objects that carries no name — the one case
+worth telling a deploy about, since it is a union the author meant and the SDL
+cannot emit.
+*/
+let isUnnamedUnion = (schema: S.t<unknown>): bool =>
+  getName(schema)->Option.isNone && armsOf(schema)->Option.isSome
+
+/**
+Stamps `__typename` into every union value inside an encoded row, in place.
+
+Written once at save rather than by each read door: both AppSync and graphql-js
+resolve a union member from `__typename` on the value they are handed, and the
+AppSync resolvers hand back the stored item unchanged. The doors that would each
+have to stamp number fourteen across three backends, and the live change channel
+— which carries the row as raw JSON, past the typed field entirely — is reachable
+from none of them. Stamping here is one place, and it is the only one both
+channels share.
+
+Driven by the schema, so a row of a view with no union field is walked and left
+byte-identical.
+*/
+let rec stampInto = (~schema: S.t<unknown>, json: JSON.t): unit =>
+  switch classify(schema) {
+  | Some((name, arms)) =>
+    switch json->JSON.Decode.object {
+    | Some(obj) =>
+      switch obj->Dict.get("TAG")->Option.flatMap(JSON.Decode.string) {
+      | Some(tag) =>
+        obj->Dict.set(typenameKey, JSON.Encode.string(memberTypeName(~union=name, ~arm=tag)))
+        // An arm's own fields may hold unions too, so the arm is walked as the
+        // record it is — the union case above cannot recurse into it, since a
+        // union's schema says nothing about which arm this value took.
+        switch arms->Array.find(a => a.tag === tag) {
+        | Some({schema: armSchema}) => stampMembers(~schema=armSchema, json)
+        | None => ()
+        }
+      | None => ()
+      }
+    | None => ()
+    }
+  | None => stampMembers(~schema, json)
+  }
+
+and stampMembers = (~schema: S.t<unknown>, json: JSON.t): unit =>
+  switch schema {
+  | Object({properties}) =>
+    switch json->JSON.Decode.object {
+    | Some(obj) =>
+      properties
+      ->Dict.toArray
+      ->Array.forEach(((name, propSchema)) =>
+        switch obj->Dict.get(name) {
+        | Some(value) => stampInto(~schema=propSchema, value)
+        | None => ()
+        }
+      )
+    | None => ()
+    }
+  | Array({items, additionalItems}) =>
+    let itemSchema = switch items->Array.get(0) {
+    | Some(itemSchema) => Some(itemSchema)
+    | None =>
+      switch additionalItems {
+      | Schema(s) => Some(s)
+      | _ => None
+      }
+    }
+    switch (itemSchema, json->JSON.Decode.array) {
+    | (Some(itemSchema), Some(values)) =>
+      values->Array.forEach(value => stampInto(~schema=itemSchema, value))
+    | _ => ()
+    }
+  | _ =>
+    // An optional field wraps its schema in a union with `undefined`; the value
+    // that reached us is the inner one either way.
+    switch Semantic.unwrapOptional(schema) {
+    | Some(inner) => stampInto(~schema=inner, json)
+    | None => ()
+    }
+  }
+
+/**
+The union fields an object schema declares, named and unnamed alike, with the
+name where there is one.
+
+The SDL emitter and the deploy-time report both need to say *which field* — a
+report that names only the view leaves the author grepping.
+*/
+let fieldsOf = (schema: S.t<unknown>): array<(string, option<string>)> =>
+  switch schema {
+  | Object({properties}) =>
+    properties
+    ->Dict.toArray
+    ->Array.filterMap(((name, propSchema)) =>
+      armsOf(propSchema)->Option.isSome ? Some((name, getName(propSchema))) : None
+    )
+  | _ => []
+  }

package/src/components/TaggedUnion.res.mjs

@@ -0,0 +1,193 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+let unionNameId = Sury.$Metadata_Id_make("reventless", "taggedUnionName");
+
+function named(name, schema) {
+  return Sury.$Metadata_set(schema, unionNameId, name);
+}
+
+function getName(schema) {
+  return Sury.$Metadata_get(schema, unionNameId);
+}
+
+function memberTypeName(union, arm) {
+  return union + arm;
+}
+
+let typenameKey = "__typename";
+
+function isPositionalName(name) {
+  if (name.startsWith("_") && name.length > 1) {
+    return name.slice(1, name.length).split("").every(c => {
+      if (c >= "0") {
+        return c <= "9";
+      } else {
+        return false;
+      }
+    });
+  } else {
+    return false;
+  }
+}
+
+function armsOf(schema) {
+  if (schema.type !== "anyOf") {
+    return;
+  }
+  let members = schema.anyOf.filter(v => {
+    switch (v.type) {
+      case "null" :
+      case "undefined" :
+        return false;
+      default:
+        return true;
+    }
+  });
+  if (members.length < 2) {
+    return;
+  }
+  let arms = Stdlib_Array.filterMap(members, member => {
+    if (member.type !== "object") {
+      return;
+    }
+    let properties = member.properties;
+    let match = properties["TAG"];
+    if (match === undefined) {
+      return;
+    }
+    if (match.type !== "string") {
+      return;
+    }
+    let tag = match.const;
+    if (tag === undefined) {
+      return;
+    }
+    let fields = Object.entries(properties).filter(param => param[0] !== "TAG");
+    if (fields.length === 0 || fields.some(param => isPositionalName(param[0]))) {
+      return;
+    } else {
+      return {
+        tag: tag,
+        schema: member
+      };
+    }
+  });
+  if (arms.length === members.length) {
+    return arms;
+  }
+}
+
+function classify(schema) {
+  let match = Sury.$Metadata_get(schema, unionNameId);
+  let match$1 = armsOf(schema);
+  if (match !== undefined && match$1 !== undefined) {
+    return [
+      match,
+      match$1
+    ];
+  }
+}
+
+function isUnnamedUnion(schema) {
+  if (Stdlib_Option.isNone(Sury.$Metadata_get(schema, unionNameId))) {
+    return Stdlib_Option.isSome(armsOf(schema));
+  } else {
+    return false;
+  }
+}
+
+function stampInto(schema, json) {
+  let match = classify(schema);
+  if (match === undefined) {
+    return stampMembers(schema, json);
+  }
+  let obj = Stdlib_JSON.Decode.object(json);
+  if (obj === undefined) {
+    return;
+  }
+  let tag = Stdlib_Option.flatMap(obj["TAG"], Stdlib_JSON.Decode.string);
+  if (tag === undefined) {
+    return;
+  }
+  obj[typenameKey] = match[0] + tag;
+  let match$1 = match[1].find(a => a.tag === tag);
+  if (match$1 !== undefined) {
+    return stampMembers(match$1.schema, json);
+  }
+}
+
+function stampMembers(schema, json) {
+  switch (schema.type) {
+    case "array" :
+      let additionalItems = schema.additionalItems;
+      let itemSchema = schema.items[0];
+      let itemSchema$1 = itemSchema !== undefined ? itemSchema : (
+          additionalItems === "strip" || additionalItems === "strict" ? undefined : additionalItems
+        );
+      let match = Stdlib_JSON.Decode.array(json);
+      if (itemSchema$1 !== undefined && match !== undefined) {
+        match.forEach(value => stampInto(itemSchema$1, value));
+        return;
+      } else {
+        return;
+      }
+    case "object" :
+      let obj = Stdlib_JSON.Decode.object(json);
+      if (obj !== undefined) {
+        Object.entries(schema.properties).forEach(param => {
+          let value = obj[param[0]];
+          if (value !== undefined) {
+            return stampInto(param[1], value);
+          }
+        });
+        return;
+      } else {
+        return;
+      }
+    default:
+      let inner = Semantic$Reventless.unwrapOptional(schema);
+      if (inner !== undefined) {
+        return stampInto(inner, json);
+      } else {
+        return;
+      }
+  }
+}
+
+function fieldsOf(schema) {
+  if (schema.type === "object") {
+    return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
+      let propSchema = param[1];
+      if (Stdlib_Option.isSome(armsOf(propSchema))) {
+        return [
+          param[0],
+          Sury.$Metadata_get(propSchema, unionNameId)
+        ];
+      }
+    });
+  } else {
+    return [];
+  }
+}
+
+export {
+  unionNameId,
+  named,
+  getName,
+  memberTypeName,
+  typenameKey,
+  isPositionalName,
+  armsOf,
+  classify,
+  isUnnamedUnion,
+  stampInto,
+  stampMembers,
+  fieldsOf,
+}
+/* unionNameId Not a pure module */

package/src/generator/PlatformCodegen.res

@@ -73,17 +73,16 @@ let splitKey = (key: string): option<(string, string)> =>
     key->String.slice(~start=i + 1),
   ))
 
-// The provenance comment quotes the annotation as its author wrote it — taken
-// from the manifest, which recorded it at the one place the owning plugin was
+// The provenance comment names the store as the field spells it — taken from
+// the manifest, which recorded it at the one place the owning plugin was
 // unambiguous. Inferring it here is what this replaced: the manifest carries a
 // deploy-manifest entry name and the key carries the registered name, and no
 // rule relates the two (`platform-inspector` against `PlatformInspector` is an
-// ordinary pairing), so any comparison here eventually quotes a string that is
+// ordinary pairing), so any comparison here eventually names a string that is
 // in no source file.
 //
-// A site with no recorded annotation predates the recording. It still names the
-// field, which is the comment's job; it just makes no claim about the source
-// text it cannot see.
+// A site with no recorded store predates the recording. It still names the
+// field, which is the comment's job; it just makes no claim it cannot support.
 let renderEntry = (entry: unionEntry): result<array<string>, string> =>
   switch splitKey(entry.key) {
   | None =>
@@ -94,8 +93,13 @@ let renderEntry = (entry: unionEntry): result<array<string>, string> =>
       let comments =
         entry.declaredBy->Array.map(site => {
           let site_ = `  // ${site.pluginName}: ${site.component}.${site.field}`
+          // `→ store` rather than `@storageRef("store")`: a field may name its
+          // store by annotation *or* by being named, and the manifest carries
+          // the store either way without saying which. Naming the annotation
+          // would send a reader looking for source text a derived field has not
+          // got.
           switch site.annotation {
-          | Some(annotation) => `${site_} @storageRef(${quote(annotation)})`
+          | Some(annotation) => `${site_} → ${annotation}`
           | None => site_
           }
         })
@@ -115,13 +119,12 @@ aggregate is keyed by the registered name — so a second plugin registering an
 existing name is not rejected but read as a **new version of the first**, and
 silently supersedes it in the registry.
 
-Ownership is read from the annotation as authored, which is the one signal that
-separates a duplicate from legitimate sharing: an **unqualified**
-`@storageRef("productImages")` means "a store of my own plugin", so the
-deployable that wrote it is the plugin the key names. A **qualified**
-`@storageRef("Catalog.productImages")` points at someone else's store and says
-nothing about who owns it — that is the sanctioned cross-plugin form and must not
-trip this.
+Ownership is read from the store as the field states it, which is the one signal
+that separates a duplicate from legitimate sharing: an **unqualified**
+`productImages` means "a store of my own plugin", so the deployable that stated
+it is the plugin the key names. A **qualified** `Catalog.productImages` points at
+someone else's store and says nothing about who owns it — that is the sanctioned
+cross-plugin form and must not trip this.
 
 Partial by construction: it can only see plugins that declare a store, because
 capability manifests are the only per-plugin input the generator reads. A

package/src/generator/PlatformCodegen.res.mjs

@@ -59,7 +59,7 @@ function renderEntry(entry) {
     let site_ = `  // ` + site.pluginName + `: ` + site.component + `.` + site.field;
     let annotation = site.annotation;
     if (annotation !== undefined) {
-      return site_ + ` @storageRef(` + JSON.stringify(annotation) + `)`;
+      return site_ + ` → ` + annotation;
     } else {
       return site_;
     }

package/src/generator/PlatformGenerator.res

@@ -95,7 +95,7 @@ let () = {
               )
               let manifest = try NodeFs.readFileSync(path)
               ->JSON.parseOrThrow
-              ->S.parseOrThrow(CapabilityManifest.schema) catch {
+              ->S.parseOrThrow(~to=CapabilityManifest.schema) catch {
               | _ => {
                   fail(`could not parse ${path} as a capability manifest`)
                   ({capabilities: []}: CapabilityManifest.t)

package/src/semantic/Bytes.res.mjs

@@ -1,6 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
 function fromFloat(raw) {
@@ -29,7 +29,7 @@ function fromFloat(raw) {
   }
 }
 
-let schema = Semantic$Reventless.refined(S.float, Semantic$Reventless.Id.bytes, fromFloat);
+let schema = Semantic$Reventless.refined(Sury.float, Semantic$Reventless.Id.bytes, fromFloat);
 
 export {
   fromFloat,

package/src/semantic/Color.res.mjs

@@ -1,6 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
 let hex = /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
@@ -19,7 +19,7 @@ function fromString(raw) {
   }
 }
 
-let schema = Semantic$Reventless.refined(S.string, Semantic$Reventless.Id.color, fromString);
+let schema = Semantic$Reventless.refined(Sury.string, Semantic$Reventless.Id.color, fromString);
 
 export {
   hex,