@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/kotlin/Entity_kotlin.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, camelify, names,
   File, Content, Folder, Fragment,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 import {
@@ -25,7 +25,7 @@ const Entity = cmp(function Entity(props: any) {
   // Collision-free entity CLASS name (see entityClassName): normally
   // `<Name>Entity`, but disambiguated (e.g. `<Name>EntityClient`) when it
   // would clash with another entity's data-type name.
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -41,7 +41,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: cls + '.' + target.ext }, () => {
 
-      const opnames = Object.keys(entity.op)
+      const opnames = Object.keys(entity.op || {})
 
       // For each CRUD op: if the spec defines it, splice in the real
       // implementation. Otherwise emit a stub that satisfies the SdkEntity

package/project/.sdk/src/cmp/kotlin/MainEntity_kotlin.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -17,7 +17,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   const kotlinpackage = kotlinPackage(model)
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
   const accessor = kotlinVarName(entity.name)
 

package/project/.sdk/src/cmp/kotlin/Main_kotlin.ts

@@ -23,6 +23,7 @@ import { Config } from './Config_kotlin'
 import { Gitignore } from './Gitignore_kotlin'
 import { MainEntity } from './MainEntity_kotlin'
 import { EntityBase } from './EntityBase_kotlin'
+import { EntityTypes } from './EntityTypes_kotlin'
 import { SdkError } from './SdkError_kotlin'
 import { kotlinPackage } from './utility_kotlin'
 
@@ -84,6 +85,11 @@ const Main = cmp(async function Main(props: any) {
     })
 
     Config({ target })
+
+    // Generate the typed reference-model file (<Name>Types.kt) beside the
+    // other generated core files. Documentation/DX shapes only — not wired
+    // into the loose-object-model op signatures.
+    EntityTypes({ target, kotlinpackage })
   })
 
 })

package/project/.sdk/src/cmp/kotlin/Package_kotlin.ts

@@ -30,7 +30,7 @@ const Package = cmp(async function Package(props: any) {
 
   // Dep name convention: "group:artifact" with an explicit version.
   const deps: { group: string, artifact: string, version: string, kind: string }[] = []
-  for (const d of collectDeps(model, target.name, target.deps)) {
+  for (const d of collectDeps(model, target.name, target.deps, ctx$.log)) {
     const [dgroup, dartifact] = String(d.name).split(':')
     if (dgroup && dartifact && d.version) {
       deps.push({

package/project/.sdk/src/cmp/kotlin/ReadmeEntity_kotlin.ts

@@ -0,0 +1,175 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { kotlinVarName } from './utility_kotlin'
+
+
+// Type names come from the shared canonToType 'kotlin' column (single source of truth).
+
+// A type-correct Kotlin literal for a field's canonical type.
+function kotlinLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'listOf<Any?>()'
+  if ('OBJECT' === k) return 'mapOf<String, Any?>()'
+  return `"${placeholder}"`
+}
+
+
+// Operation method spelling for Kotlin: camelCase methods over the loose
+// object model. The op descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match, null)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(null, null)',    desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data, null)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data, null)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match, null)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Sanitise the local variable name — a camelCased Kotlin keyword gets a
+    // trailing underscore (kotlinVarName) so the snippet compiles.
+    const eVar = kotlinVarName(entity.name)
+    const accessor = kotlinVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`val ${eVar} = client.${accessor}(null)\`
+
+`)
+
+    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')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      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
+        ? `mutableMapOf<String, Any?>(${loadItems.map((it: any) =>
+          `"${it.name}" to ${kotlinLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')})`
+        : 'null'
+      Content(`#### Example: Load
+
+\`\`\`kotlin
+val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`kotlin
+val ${eVar}List = client.${accessor}(null).list(null, null)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`kotlin
+val ${eVar} = client.${accessor}(null).create(mutableMapOf<String, Any?>(
+`)
+      createItems.map((it: any, i: number) => {
+        const comma = i < createItems.length - 1 ? ',' : ''
+        Content(`    "${it.name}" to ${kotlinLit(it.type, 'example_' + it.name)}${comma}  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`), null)
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

package/project/.sdk/src/cmp/kotlin/ReadmeExamplesTest_kotlin.ts

@@ -0,0 +1,198 @@
+
+import { cmp, File, Content } from '@voxgig/sdkgen'
+
+import { kotlinPackage } from './utility_kotlin'
+
+
+// Emits test/ReadmeExamplesTest.kt — a JUnit PRESENCE + STRUCTURE gate over
+// every ```kotlin fenced block in the repository ROOT README.md, the
+// per-language kotlin/README.md, AND the per-language kotlin/REFERENCE.md.
+//
+// SCOPE NOTE (deliberate, documented): the Python/TS/Go equivalents EXECUTE and
+// type-check every documented block. That is infeasible here — the generated
+// Kotlin SDK compiles with Gradle/kotlinc only (no in-process Kotlin compiler
+// dependency wired into the test classpath), so a test cannot compile-and-run
+// arbitrary doc snippets at test time. This gate therefore guarantees the
+// weaker-but-real invariant that keeps the docs honest as the generator evolves:
+//   1. every doc exists and contains at least one ```kotlin block (nothing was
+//      dropped);
+//   2. every ```kotlin block is structurally well-formed — its braces,
+//      parentheses and brackets balance (catches a truncated or malformed
+//      generated snippet).
+// A per-doc summary line makes the coverage visible in the test output.
+//
+// The emitted Kotlin is written WITHOUT literal backticks (the fence marker is
+// built at runtime as 96.toChar().toString().repeat(3)) so this TS template
+// literal stays clean.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const Name = model.const.Name
+  const kotlinpackage = props.kotlinpackage || kotlinPackage(model)
+
+  File({ name: 'ReadmeExamplesTest.' + target.ext }, () => {
+    Content(`package ${kotlinpackage}.sdktest
+
+// ${Name} SDK — documentation kotlin-examples PRESENCE + STRUCTURE gate.
+//
+// GUARANTEE (see ReadmeExamplesTest_kotlin.ts for why this is a structure gate
+// and not an execute gate): every kotlin example in the docs is accounted for.
+// This JUnit class is a completeness gate over every ${'```'}kotlin fenced code
+// block in three documents:
+//   - the repository ROOT README.md (one directory above this module),
+//   - the per-language kotlin/README.md,
+//   - the per-language kotlin/REFERENCE.md.
+//
+// Checks, PER DOCUMENT:
+//   1. PRESENCE: the doc exists and holds at least one kotlin block.
+//   2. STRUCTURE: every kotlin block's braces / parens / brackets balance, so a
+//      truncated or malformed generated snippet fails loudly. Every code fence
+//      is also terminated (even fence count), so an unclosed fence at EOF is
+//      caught rather than accepted as a complete block.
+//
+// GENERATED by @voxgig/sdkgen — do not edit by hand.
+
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+
+import java.io.File
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.Paths
+
+class ReadmeExamplesTest {
+
+  // The three documents to scan, resolved relative to the Gradle module
+  // directory (the working directory when the test task runs). Each row is
+  // {label, relative path}.
+  private fun docs(): Array<Array<String>> {
+    return arrayOf(
+      arrayOf("root README", ".." + File.separator + "README.md"),
+      arrayOf("kotlin README.md", "README.md"),
+      arrayOf("kotlin REFERENCE.md", "REFERENCE.md"),
+    )
+  }
+
+  // Extract every kotlin fenced block. Split on the triple-backtick fence:
+  // odd-indexed segments are the inside of a fenced block (info string on the
+  // first line, then the code). Only blocks whose info string is exactly
+  // "kotlin" are returned.
+  private fun kotlinBlocks(text: String): List<String> {
+    val fence = 96.toChar().toString().repeat(3)
+    val parts = text.split(fence)
+    val blocks = mutableListOf<String>()
+    var i = 1
+    while (i < parts.size) {
+      val seg = parts[i]
+      val nl = seg.indexOf('\\n')
+      val info = (if (nl < 0) seg else seg.substring(0, nl)).trim()
+      if (info == "kotlin") {
+        blocks.add(if (nl < 0) "" else seg.substring(nl + 1))
+      }
+      i += 2
+    }
+    return blocks
+  }
+
+  private fun readDoc(path: Path, label: String): String {
+    assertTrue(Files.exists(path), label + " not found: " + path)
+    return Files.readString(path)
+  }
+
+  // Count triple-backtick fence markers. A well-formed document opens and
+  // closes every fenced block, so the total must be EVEN. An odd count means a
+  // fence was opened but never closed (a truncated / malformed doc) — the
+  // split-based extraction in kotlinBlocks() would otherwise accept the
+  // unterminated trailing segment as a complete block and pass silently.
+  private fun fenceCount(text: String): Int {
+    val fence = 96.toChar().toString().repeat(3)
+    var count = 0
+    var idx = text.indexOf(fence)
+    while (idx >= 0) {
+      count++
+      idx = text.indexOf(fence, idx + fence.length)
+    }
+    return count
+  }
+
+  // True when every open/close delimiter balances (ignores the subtlety of
+  // delimiters inside string literals — a generated snippet never nests an
+  // unbalanced delimiter in a string, and this catches truncation).
+  private fun balanced(block: String): Boolean {
+    val stack = ArrayDeque<Char>()
+    val pairs = mapOf('(' to ')', '[' to ']', '{' to '}')
+    for (ch in block) {
+      if (pairs.containsKey(ch)) {
+        stack.addLast(pairs[ch]!!)
+      }
+      else if (ch == ')' || ch == ']' || ch == '}') {
+        if (stack.isEmpty() || stack.removeLast() != ch) {
+          return false
+        }
+      }
+    }
+    return stack.isEmpty()
+  }
+
+  @Test
+  fun rootReadmeHasKotlinBlocks() {
+    val doc = docs()[0]
+    val blocks = kotlinBlocks(readDoc(Paths.get(doc[1]), doc[0]))
+    assertTrue(blocks.size > 0, "expected at least one kotlin block in " + doc[0])
+  }
+
+  @Test
+  fun localReadmeHasKotlinBlocks() {
+    val doc = docs()[1]
+    val blocks = kotlinBlocks(readDoc(Paths.get(doc[1]), doc[0]))
+    assertTrue(blocks.size > 0, "expected at least one kotlin block in " + doc[0])
+  }
+
+  @Test
+  fun referenceHasKotlinBlocks() {
+    val doc = docs()[2]
+    val blocks = kotlinBlocks(readDoc(Paths.get(doc[1]), doc[0]))
+    assertTrue(blocks.size > 0, "expected at least one kotlin block in " + doc[0])
+  }
+
+  @Test
+  fun allKotlinBlocksAreStructurallyBalanced() {
+    val failures = mutableListOf<String>()
+    for (doc in docs()) {
+      val path = Paths.get(doc[1])
+      if (!Files.exists(path)) {
+        continue
+      }
+      val src = readDoc(path, doc[0])
+      // A fence opened but never closed is a malformed doc — fail loudly
+      // rather than silently accepting the unterminated trailing segment as a
+      // complete block.
+      if (fenceCount(src) % 2 != 0) {
+        failures.add(doc[0] + " has an unterminated code fence")
+      }
+      val blocks = kotlinBlocks(src)
+      var balancedCount = 0
+      for (i in blocks.indices) {
+        if (balanced(blocks[i])) {
+          balancedCount++
+        }
+        else {
+          failures.add(doc[0] + " kotlin block #" + i +
+              " has unbalanced delimiters:\\n\\n" + blocks[i])
+        }
+      }
+      println(
+          "[readme-examples] " + doc[0] + " kotlin blocks: total=" +
+          blocks.size + " balanced=" + balancedCount)
+    }
+    assertTrue(failures.isEmpty(), failures.joinToString("\\n\\n"))
+  }
+}
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/kotlin/ReadmeExplanation_kotlin.ts

@@ -0,0 +1,47 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import { kotlinPackage } from './utility_kotlin'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const pkg = kotlinPackage(model)
+
+  Content(`### Data as maps
+
+The Kotlin SDK uses a loose object model — \`MutableMap<String, Any?>\`
+throughout — rather than a bespoke typed class per endpoint. This mirrors the
+dynamic nature of the API and keeps the SDK flexible: no regeneration is
+needed when the API schema changes.
+
+Use \`Helpers.toMapAny(value)\` to safely coerce a value to a
+\`MutableMap<String, Any?>\`. A \`${model.const.Name}Types.kt\` module of
+reference \`data class\` types is also generated for editor documentation.
+
+### Project structure
+
+\`\`\`
+kotlin/
+├── build.gradle.kts            -- Gradle build (compiles core/, utility/, feature/, entity/)
+├── settings.gradle.kts         -- Gradle project settings
+├── core/                       -- Main SDK client, config, entity base, error type
+├── entity/                     -- Entity implementations
+├── feature/                    -- Built-in features (Base, Test, Log, ...)
+├── utility/                    -- Utility functions and the vendored struct library
+└── test/                       -- JUnit test suites
+\`\`\`
+
+The main client class (\`${model.const.Name}SDK\`, package \`${pkg}.core\`)
+exposes the entity accessors. Reference entity or utility types directly only
+when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

package/project/.sdk/src/cmp/kotlin/ReadmeHowto_kotlin.ts

@@ -0,0 +1,154 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { kotlinVarName } from './utility_kotlin'
+
+
+// A type-correct Kotlin literal for a field's canonical type.
+function kotlinLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'listOf<Any?>()'
+  if ('OBJECT' === k) return 'mapOf<String, Any?>()'
+  return '"example"'
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const SDK = model.const.Name + 'SDK'
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Pick an entity with a real op (prefer a read op). primaryOp is null only
+  // when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const eVar = exampleEntity ? kotlinVarName(exampleEntity.name) : 'entity'
+  const accessor = exampleEntity ? kotlinVarName(exampleEntity.name) : 'entity'
+  // Model-driven id key: null when the entity has no id-like field, so a
+  // match op takes an empty match.
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = 'null'
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `mutableMapOf<String, Any?>("${idF}" to "test01")` : 'null'
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => it.name !== idF && it.name !== 'id')
+    const required = items.filter((it: any) => !it.optional)
+    const chosen = required.length ? required : items.slice(0, 3)
+    testArg = `mutableMapOf<String, Any?>(${chosen.map((it: any) =>
+      `"${it.name}" to ${kotlinLit(it.type)}`).join(', ')})`
+  }
+
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
+  const testModeExample = primaryOp
+    ? `// Entity ops return the bare record and raise on error.
+val ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null)
+// ${eVar} holds the mock response record
+println(${eVar})`
+    : `val result = client.direct(mutableMapOf<String, Any?>(
+    "path" to "/api/resource",
+    "method" to "GET"))
+println(result)`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`kotlin
+val result = client.direct(mutableMapOf<String, Any?>(
+    "path" to "/api/resource/{id}",
+    "method" to "GET",
+    "params" to mapOf("id" to "example")))
+
+if (result["ok"] == true) {
+    println(result["status"])  // 200
+    println(result["data"])    // response body
+}
+else {
+    // A non-2xx response carries status + data (the error body); a
+    // transport-level failure carries err instead. Only one is present, so
+    // an absent key simply reads as null.
+    println("" + result["status"] + " " + result["err"])
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`kotlin
+// prepare() returns the fetch definition and raises on error.
+val fetchdef = client.prepare(mutableMapOf<String, Any?>(
+    "path" to "/api/resource/{id}",
+    "method" to "DELETE",
+    "params" to mapOf("id" to "example")))
+
+println(fetchdef["url"])
+println(fetchdef["method"])
+println(fetchdef["headers"])
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`kotlin
+val client = ${SDK}.testSDK(null, null)
+
+${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own \`BiFunction\`:
+
+\`\`\`kotlin
+val mockFetch = java.util.function.BiFunction<String, MutableMap<String, Any?>, Any?> { url, init ->
+    mutableMapOf<String, Any?>(
+        "status" to 200,
+        "statusText" to "OK",
+        "headers" to mutableMapOf<String, Any?>(),
+        "json" to java.util.function.Supplier<Any?> { mapOf("id" to "mock01") },
+    )
+}
+
+val client = ${SDK}(mutableMapOf<String, Any?>(
+    "base" to "http://localhost:8080",
+    "system" to mapOf("fetch" to mockFetch),
+))
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd kotlin && gradle test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}