@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/dart/fragment/Entity.test.fragment.dart

@@ -17,46 +17,7 @@ void tests() {
       ok(null != ent);
     });
 
-    test('stream', (t) async {
-      // stream() runs the list op through the full pipeline and yields each
-      // result item. Seed two entities via test mode; with the `streaming`
-      // feature active it yields the feature's incremental items, else it
-      // falls back to the materialised items — either way every item yields.
-      final seed = <String, dynamic>{
-        'entity': {
-          'entityname': {
-            'strm01': <String, dynamic>{'id': 'strm01'},
-            'strm02': <String, dynamic>{'id': 'strm02'},
-          }
-        }
-      };
-
-      final sdkopts = <String, dynamic>{};
-      if (null != config.feature['streaming']) {
-        sdkopts['feature'] = {
-          'streaming': {'active': true}
-        };
-      }
-
-      final testsdk = ProjectNameSDK.test(seed, sdkopts);
-      final ent = testsdk.EntityName();
-
-      final seen = [];
-      await for (final item in ent.stream('list', <String, dynamic>{})) {
-        seen.add(item);
-      }
-      equal(2, seen.length);
-
-      // Fallback: with streaming inactive, stream() still yields both items
-      // from the materialised result.
-      final plainsdk = ProjectNameSDK.test(seed);
-      final plainent = plainsdk.EntityName();
-      final seen2 = [];
-      await for (final item in plainent.stream('list', <String, dynamic>{})) {
-        seen2.add(item);
-      }
-      equal(2, seen2.length);
-    });
+    // <[SLOT:stream]>
 
     test('basic', (t) async {
       // <[SLOT:basic]>

package/project/.sdk/src/cmp/dart/fragment/Main.fragment.dart

@@ -5,9 +5,9 @@ import 'dart:async';
 
 import 'Config.dart';
 import 'Spec.dart';
-import 'ProjectNameEntityBase.dart';
-import 'ProjectNameError.dart';
-import 'feature/base/BaseFeature.dart';
+// ProjectNameEntityBase / ProjectNameError / BaseFeature are re-exported below;
+// a Dart `export` needs no matching `import`, so importing them here too is an
+// unused_import. Keep only the imports actually referenced in this file.
 import 'utility/ErrUtility.dart';
 import 'utility/Utility.dart';
 

package/project/.sdk/src/cmp/elixir/EntityTypes_elixir.ts

@@ -0,0 +1,165 @@
+
+
+// Typed-model generator (Elixir target). Port of EntityTypes_ts.ts / _rb.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one module, lib/<app>_types.ex,
+// holding an `@type` alias per active entity plus a request/match type per
+// active op, each with a `@typedoc` documenting its concrete members.
+//
+// TYPE CHOICE: the SDK carries data as string-keyed struct value nodes, and
+// Elixir map typespecs cannot pin individual string keys (only
+// `optional(String.t()) => v`), so every alias resolves to an open string-keyed
+// map `%{optional(String.t()) => any()}`. The precise per-member shape is
+// documented in the accompanying @typedoc (the honest Elixir analogue of the
+// TS interface / rb Struct). Field/param sentinels ($STRING, $INTEGER, ...) are
+// turned into real Elixir typespec fragments (String.t(), integer(), ...) by
+// the shared sdkgen canonToType 'elixir' column (via the `elixirType`
+// delegate in utility_elixir).
+//
+// Op type-name scheme mirrors every other language — derived from the SHARED
+// OP_SUFFIX policy, snake_cased for Elixir:
+//   <ename>, <ename>_load_match, <ename>_list_match, <ename>_create_data,
+//   <ename>_update_data, <ename>_remove_match.
+// The generated entity modules reference these aliases from @spec annotations
+// on their op functions (see fragment/Entity*Op.fragment.ex).
+
+import {
+  cmp, each, names,
+  File, Folder, Content,
+} from '@voxgig/sdkgen'
+
+import { opRequestShape, OP_SUFFIX, warnEntityTypeCollisions } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { elixirType } from './utility_elixir'
+
+
+// Snake_case op type name, derived from the SHARED OP_SUFFIX policy (the
+// PascalCase scheme <Name><Op><Match|Data> rendered Elixir-style):
+//   <ename>_load_match, <ename>_create_data, ...
+function elixirOpTypeName(ename: string, opname: string): string {
+  return ename + '_' + opname + '_' + (OP_SUFFIX[opname] || 'Match').toLowerCase()
+}
+
+
+// Emit one `@typedoc` + `@type` alias. The alias is always an open
+// string-keyed map; the members are documented in the doc block.
+function emitType(
+  typeName: string,
+  doc: string,
+  members: Array<{ name: string, type: unknown, optional: boolean }>,
+): void {
+  let block = `  @typedoc """\n  ${doc}\n`
+
+  if (0 < members.length) {
+    block += `\n  Members:\n`
+    members.forEach((m) => {
+      const req = m.optional ? ' (optional)' : ' (required)'
+      block += `    * \`"${m.name}"\` — ${elixirType(m.type)}${req}\n`
+    })
+  }
+
+  block += `  """\n  @type ${typeName} :: %{optional(String.t()) => any()}\n\n`
+
+  Content(block)
+}
+
+
+const LANG = 'elixir'
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+
+  const Name = model.const.Name
+  const app = model.const.name.toLowerCase()
+
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets an entity module: the consumer scaffold
+  // (create-sdkgen Root.ts) iterates entities WITHOUT an active filter, and
+  // each generated module carries @specs referencing its Types aliases, so an
+  // alias is required for each or the project won't compile. Filter on `name`
+  // (always present), NOT `active` — parity with the go emitter's fix.
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
+  // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
+  // entity not yet named would otherwise read `Name = undefined` below.
+  entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
+  Folder({ name: 'lib' }, () => {
+    File({ name: app + '_types.ex' }, () => {
+
+      Content(`# Typed models for the ${Name} SDK.
+#
+# GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+# params (op.<name>.points[].args.params[]). Member types come from the
+# canonical type sentinels. The SDK carries data as string-keyed struct value
+# nodes, so each alias is an open string-keyed map; the @typedoc member lists
+# document the concrete shapes. Do not edit by hand.
+
+defmodule ${Name}.Types do
+  @moduledoc """
+  Documented shapes for the ${Name} SDK entities and operation payloads.
+
+  Every alias resolves to an open string-keyed map because the SDK carries
+  data as string-keyed struct value nodes; consult each type's member list for
+  the concrete field/param types.
+  """
+
+`)
+
+      entityList.forEach((ent: any) => {
+        const EName = ent.Name
+        const ename = ent.name
+        const fields = (ent.fields ? each(ent.fields) : [])
+          .filter((f: any) => f.active !== false)
+
+        // Entity data model: one member per field (`req:false` -> optional).
+        emitType(
+          ename,
+          `${EName} entity data model.`,
+          fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req })),
+        )
+
+        // Per active op: a request/match type. Members and their optionality
+        // come from the shared partiality policy (opRequestShape).
+        const ops = ent.op || {}
+        ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+          if (null == ops[opname]) {
+            return
+          }
+
+          const typeName = elixirOpTypeName(ename, opname)
+          const { items } = opRequestShape(ent, opname)
+
+          emitType(
+            typeName,
+            `Request payload for ${EName} ${opname}.`,
+            items,
+          )
+        })
+      })
+
+      Content(`end
+`)
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/elixir/Main_elixir.ts

@@ -17,6 +17,7 @@ import { Package } from './Package_elixir'
 import { Config } from './Config_elixir'
 import { Gitignore } from './Gitignore_elixir'
 import { MainEntity } from './MainEntity_elixir'
+import { EntityTypes } from './EntityTypes_elixir'
 
 
 // #`-comment hook marker key (gotcha #1: jostraca's built-in #Name-Tag
@@ -44,6 +45,9 @@ const Main = cmp(async function Main(props: any) {
   Package({ target })
   Gitignore({})
 
+  // Generate the documented typespec module (lib/<app>_types.ex).
+  EntityTypes({ target })
+
   // Copy tm/elixir verbatim (with ProjectName/projectname substitution).
   Copy({
     from: 'tm/' + target.name,

package/project/.sdk/src/cmp/elixir/Package_elixir.ts

@@ -20,7 +20,9 @@ const Package = cmp(async function Package(props: any) {
   const model: Model = ctx$.model
 
   const Name = model.const.Name
-  const app = model.const.name
+  // Elixir app names are atoms: a hyphenated slug (`bluefin-decryptx-p2pe`)
+  // is invalid (`:a-b` parses as subtraction). Snake_case it.
+  const app = String(model.const.name).replace(/-/g, '_')
   const { repoUrl } = repoInfo(model)
 
   File({ name: 'mix.exs' }, () => {

package/project/.sdk/src/cmp/elixir/ReadmeEntity_elixir.ts

@@ -0,0 +1,163 @@
+
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+// Type names come from the shared canonToType 'elixir' column (single source of truth).
+import { elixirLit } from './utility_elixir'
+
+
+// Operation method spelling for the Elixir target: each op is a function on
+// the entity's module taking the entity handle first. The descriptions are
+// language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(entity, match)',  desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(entity)',         desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(entity, data)', desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(entity, data)', desc: 'Update an existing entity.' },
+  remove: { method: 'remove(entity, match)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const Name = model.const.Name
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+Every operation lives on the entity's \`${Name}.Entity.<Name>\` module and
+takes an entity handle built from the client:
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const EName = entity.Name
+    const eVar = entity.name
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    const idF = entityIdField(entity)
+
+    Content(`
+### ${EName}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create a handle: \`${eVar} = ${Name}.${eVar}(sdk)\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `${Name}.Helpers.deep(%{${loadItems.map((it: any) =>
+          `"${it.name}" => ${elixirLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}})`
+        : `${Name}.Helpers.deep(%{})`
+      Content(`#### Example: Load
+
+\`\`\`elixir
+${eVar} = ${Name}.${eVar}(sdk)
+record = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`elixir
+${eVar} = ${Name}.${eVar}(sdk)
+records = ${Name}.Entity.${EName}.list(${eVar})
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — with a real,
+      // executable literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`elixir
+${eVar} = ${Name}.${eVar}(sdk)
+record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
+`)
+      createItems.map((it: any) => {
+        Content(`  "${it.name}" => ${elixirLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`}))
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

package/project/.sdk/src/cmp/elixir/ReadmeExamplesTest_elixir.ts

@@ -0,0 +1,126 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Emits elixir/test/readme_examples_test.exs — an ExUnit SYNTAX + PRESENCE
+// gate over every ```elixir fenced block in the three docs that ship elixir
+// examples: the repository ROOT README.md, the per-language elixir/README.md,
+// and the per-language elixir/REFERENCE.md.
+//
+// For each block, tagged by (source doc, index), the gate PARSES it with
+// `Code.string_to_quoted/1` — catching malformed examples (a missing `end`, a
+// bad token, an unbalanced `%{}`). It also asserts each doc that exists ships
+// at least one elixir block.
+//
+// SCOPE NOTE: unlike the Python/Lua gates this does NOT execute blocks in a
+// seeded offline subprocess. Elixir's compile model makes running a README
+// fragment against the generated `<Name>` modules substantially heavier (each
+// block would need the SDK compiled and loaded, and the narrative aliases
+// resolved), so this port stops at the syntax gate — a real, useful guard that
+// keeps documented examples parseable as the generator evolves.
+//
+// The emitted Elixir avoids backticks (chr 96 via <<96>>) so this TS template
+// literal stays clean; the only interpolation is the SDK module name.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+
+  const Name = model.const.Name
+
+  File({ name: 'readme_examples_test.exs' }, () => {
+    Content(`# ${Name} SDK — documentation elixir-examples syntax gate.
+#
+# SYNTAX + PRESENCE gate over every elixir fenced code block in three docs:
+#   - the repository ROOT README.md (one directory above the elixir/ package),
+#   - the per-language elixir/README.md,
+#   - the per-language elixir/REFERENCE.md.
+#
+# Every block is parsed with Code.string_to_quoted/1 so a malformed documented
+# example (missing end, unbalanced map, bad token) fails the suite. Generated
+# by @voxgig/sdkgen — do not edit by hand.
+
+defmodule ${Name}.ReadmeExamplesTest do
+  use ExUnit.Case
+
+  # The triple-backtick markdown fence, built without literal backticks.
+  @fence String.duplicate(<<96>>, 3)
+
+  @pkg_root Path.expand("..", __DIR__)
+  @docs [
+    {"root README", Path.expand("../README.md", @pkg_root)},
+    {"elixir README.md", Path.join(@pkg_root, "README.md")},
+    {"elixir REFERENCE.md", Path.join(@pkg_root, "REFERENCE.md")}
+  ]
+
+  # Return the code bodies of every elixir-tagged fenced block in \`text\`.
+  # Splitting on the fence yields alternating outside/inside segments; the
+  # odd-indexed ones are inside a fence. Keep only those whose info string
+  # (first line) is exactly "elixir".
+  defp elixir_blocks(text) do
+    text
+    |> String.split(@fence)
+    |> Enum.with_index()
+    |> Enum.filter(fn {_seg, i} -> rem(i, 2) == 1 end)
+    |> Enum.map(fn {seg, _i} -> seg end)
+    |> Enum.filter(fn seg ->
+      [info | _] = String.split(seg, "\\n")
+      String.trim(info) == "elixir"
+    end)
+    |> Enum.map(fn seg ->
+      [_info | rest] = String.split(seg, "\\n")
+      Enum.join(rest, "\\n")
+    end)
+  end
+
+  defp doc_blocks(path) do
+    case File.read(path) do
+      {:ok, text} -> {:present, elixir_blocks(text)}
+      _ -> :absent
+    end
+  end
+
+  test "documented elixir examples parse" do
+    {failures, present, total} =
+      Enum.reduce(@docs, {[], 0, 0}, fn {label, path}, {fails, present, total} ->
+        case doc_blocks(path) do
+          :absent ->
+            {fails, present, total}
+
+          {:present, blocks} ->
+            block_fails =
+              blocks
+              |> Enum.with_index()
+              |> Enum.flat_map(fn {block, i} ->
+                case Code.string_to_quoted(block) do
+                  {:ok, _ast} ->
+                    []
+
+                  {:error, reason} ->
+                    [
+                      label <>
+                        " elixir block #" <>
+                        Integer.to_string(i) <>
+                        " failed to parse: " <>
+                        inspect(reason) <> "\\n\\n" <> block
+                    ]
+                end
+              end)
+
+            {fails ++ block_fails, present + 1, total + length(blocks)}
+        end
+      end)
+
+    assert failures == [], Enum.join(failures, "\\n\\n")
+
+    # At least one doc must be present and carry at least one elixir example.
+    assert present > 0, "no README/REFERENCE docs found to scan for elixir examples"
+    assert total > 0, "expected at least one elixir example block across the docs"
+  end
+end
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/elixir/ReadmeExplanation_elixir.ts

@@ -0,0 +1,55 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const app = model.const.name.toLowerCase()
+
+  Content(`### Data as struct value nodes
+
+The Elixir SDK models every runtime object — clients, contexts, results and
+record data — as reference-stable struct value nodes from the vendored
+\`Voxgig.Struct\` library rather than as compile-time structs. This mirrors
+the dynamic nature of the API and lets a feature hook mutate a shared node
+that every later pipeline stage observes — the immutable-Elixir way to honour
+the shared-mutable hook contract.
+
+Build inputs from native Elixir maps with \`${model.Name}.Helpers.deep/1\`,
+and read fields off results with \`Voxgig.Struct.getprop/2\`.
+
+### Module structure
+
+\`\`\`
+elixir/
+├── lib/
+│   ├── ${app}.ex                 -- Main SDK module (entity factories)
+│   ├── config.ex                 -- Resolved configuration
+│   ├── features.ex               -- Feature factory
+│   ├── pipeline.ex               -- Operation pipeline
+│   └── ${app}/
+│       ├── context.ex            -- Operation context
+│       ├── entity_base.ex        -- Shared entity behaviour
+│       ├── error.ex              -- SDK error type
+│       ├── feature.ex            -- Built-in features
+│       ├── helpers.ex            -- Value helpers (deep/1, ...)
+│       ├── json.ex               -- JSON encode/decode
+│       └── utility.ex            -- Utility functions
+│   └── entity/                   -- Per-entity modules
+├── mix.exs                       -- Package manifest
+└── test/                         -- ExUnit suites
+\`\`\`
+
+The main module \`${model.Name}\` exposes the SDK constructors and one entity
+factory function per entity. Call an operation on the matching
+\`${model.Name}.Entity.<Name>\` module.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}