@voxgig/sdkgen 1.2.1 → 1.3.1

package/project/.sdk/src/cmp/lua/Package_lua.ts

@@ -4,6 +4,9 @@ import {
   File,
   cmp,
   collectDeps,
+  pkgDescription,
+  keywords,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -24,23 +27,39 @@ const Package = cmp(async function Package(props: any) {
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const rockName = `${ns}-${pkgBase}`
+  const { repoUrl, issuesUrl } = repoInfo(model)
+  const labels = keywords(model).map((k) => `"${k}"`).join(', ')
+
+  // Single source for the version so the rockspec version and the source.tag
+  // (which `make publish` pushes as lua/v<rockVersion>) can never drift apart.
+  const rockVersion = '0.0.1'
 
   File({ name: model.name + '.rockspec' }, () => {
     Content(`package = "${rockName}"
-version = "0.0-1"
+version = "${rockVersion}-1"
 source = {
-  url = "git://github.com/${ns}/${model.name}-sdk.git"
+  -- git+https (GitHub dropped git:// in 2022); pin the install to the release
+  -- tag pushed by \`make publish\`, and point at the lua/ subdir of the monorepo.
+  url = "git+https://github.com/${ns}/${model.name}-sdk.git",
+  tag = "lua/v${rockVersion}",
+  dir = "${model.name}-sdk/lua"
 }
 description = {
-  summary = "${model.const.Name} SDK for Lua",
-  license = "MIT"
+  summary = "${pkgDescription(model, 'lua')}",
+  homepage = "${repoUrl}",
+  issues_url = "${issuesUrl}",
+  license = "MIT",
+  labels = { ${labels} }
 }
 dependencies = {
   "lua >= 5.3",
   "dkjson >= 2.5",
 `)
 
+    const seen = new Set<string>(['lua', 'dkjson'])
     for (const d of collectDeps(model, target.name, target.deps)) {
+      if (seen.has(d.name)) continue
+      seen.add(d.name)
       const v = d.source === 'target' ? (d.version || '0.0') : d.version
       Content(`  "${d.name} >= ${v}",
 `)

package/project/.sdk/src/cmp/lua/ReadmeEntity_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -41,6 +41,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   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)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +55,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`local ${entity.name} = client:${entity.Name}(nil)\`
 
 `)
 
@@ -84,7 +86,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -95,8 +97,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     if (opnames.includes('load')) {
       Content(`#### Example: Load
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`lua
+local ${entity.name}, err = client:${entity.Name}():load(${idF ? `{ ${idF} = "${entity.name}_id" }` : ''})
 \`\`\`
 
 `)
@@ -105,8 +107,8 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
     if (opnames.includes('list')) {
       Content(`#### Example: List
 
-\`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`lua
+local ${entity.name}s, err = client:${entity.Name}():list()
 \`\`\`
 
 `)
@@ -115,12 +117,12 @@ const ${entity.name}s = await client.${entity.Name}().list()
     if (opnames.includes('create')) {
       Content(`#### Example: Create
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+\`\`\`lua
+local ${entity.name}, err = client:${entity.Name}():create({
 `)
       each(fields, (field: any) => {
         if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+          Content(`  ${field.name} = nil, -- ${canonToType(field.type, target.name)}
 `)
         }
       })

package/project/.sdk/src/cmp/lua/ReadmeExamplesTest_lua.ts

@@ -0,0 +1,293 @@
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Emits lua/test/readme_examples_test.lua — a busted spec that is a
+// COMPLETENESS GATE over every ```lua block in ALL THREE docs that ship
+// lua examples:
+//   - the root README.md (top-level, multi-language quick start)
+//   - the per-language lua/README.md
+//   - the per-language lua/REFERENCE.md
+//
+// For every ```lua block, tagged by (source doc, index):
+//   1. Syntax: it must compile with Lua's load() — catches malformed
+//      example code (missing end, bad token, ...).
+//   2. Offline run: every RUNNABLE block (one that builds a client via
+//      sdk.new/sdk.test or references `client`) is EXECUTED with the mock
+//      transport (no network). Each client constructor is rewritten to the
+//      seeded test-mode form, and fragments that only use `client` get a
+//      seeded test client injected. A call to a method that does not exist
+//      — e.g. a lowercase entity accessor after the API capitalised it to
+//      client:Entity() — raises "call a nil value" and FAILS the test.
+//      Entity operations return a (value, err) tuple, so a seeded-fixture
+//      miss surfaces as a tolerated (nil, err) not-found domain error.
+//   3. Completeness: every block is partitioned into {executed, illustration}
+//      and total == executed + illustration is asserted per doc. A block that
+//      is neither runnable nor a NARROW explicit illustration (a comment-only
+//      / --[[ ]] placeholder) is a silently-untested example and FAILS the
+//      gate — "illustration" is never a catch-all.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+
+  // Every active entity, keyed by its model name, is seeded with a `test01`
+  // fixture whose id is `test01` — so a load({ id = "test01" }) in a doc
+  // resolves offline. Bracket-string keys keep the literal valid for any
+  // entity name.
+  const entity = getModelPath(model, `main.${KIT}.entity`) || {}
+  const entnames = Object.values(entity)
+    .filter((e: any) => e && e.active !== false)
+    .map((e: any) => e.name)
+
+  const seedEntries = entnames
+    .map((n: string) => `["${n}"] = { ["test01"] = { id = "test01" } }`)
+    .join(', ')
+  const seedLiteral = `{ entity = { ${seedEntries} } }`
+
+  File({ name: 'readme_examples_test.lua' }, () => {
+    Content(`-- README lua example snippets check. Generated by @voxgig/sdkgen.
+--
+-- COMPLETENESS GATE over every \`\`\`lua block in all three docs that ship
+-- lua examples: the root README.md, the lua/README.md, and the
+-- lua/REFERENCE.md. For every block:
+--   1. Syntax: each block must compile with Lua's load().
+--   2. Offline run: every runnable block (one that builds a client or
+--      references \`client\`) is EXECUTED with the mock transport (no
+--      network). Each client constructor is rewritten to the seeded
+--      test-mode form, and fragments that only use \`client\` get a seeded
+--      test client injected. A call to a method that does not exist raises
+--      "call a nil value" and FAILS the test. A seeded-fixture miss surfaces
+--      as a tolerated (nil, err) not-found domain error, not a raised error.
+--   3. Completeness: total == executed + illustration per doc. A block that
+--      is neither runnable nor an explicit comment-only placeholder FAILS
+--      the gate, so no runnable example can be silently skipped.
+
+local SDK_MODULE = "${model.name}_sdk"
+
+-- A test-mode client seeded with a fixture for every entity. The constructor
+-- of each runnable snippet is rewritten to this form so the offline mock has
+-- data to return.
+local TEST_SEED = '${seedLiteral}'
+local TEST_CTOR = "sdk.test(" .. TEST_SEED .. ")"
+
+local function script_dir()
+  local src = debug.getinfo(1, "S").source
+  local path = src:sub(1, 1) == "@" and src:sub(2) or src
+  return path:match("^(.*)[/\\\\][^/\\\\]*$") or "."
+end
+
+-- Read a doc by its path relative to this test file's directory (which is
+-- <repo>/lua/test). The root README is two levels up; the lua docs are one.
+local function read_doc(relpath)
+  local dir = script_dir()
+  local candidates = {
+    dir .. "/" .. relpath,
+    relpath,
+  }
+  for _, p in ipairs(candidates) do
+    local f = io.open(p, "r")
+    if f then
+      local data = f:read("*a")
+      f:close()
+      return data, p
+    end
+  end
+  return nil
+end
+
+local function trim(s)
+  return (s:gsub("^%s+", ""):gsub("%s+$", ""))
+end
+
+local function extract_blocks(md, lang)
+  local blocks = {}
+  local open = "\`\`\`" .. lang
+  local in_block = false
+  local cur = {}
+  for line in (md .. "\\n"):gmatch("([^\\n]*)\\n") do
+    local t = trim(line)
+    if not in_block then
+      if t == open then
+        in_block = true
+        cur = {}
+      end
+    else
+      if t == "\`\`\`" then
+        table.insert(blocks, table.concat(cur, "\\n"))
+        in_block = false
+      else
+        table.insert(cur, line)
+      end
+    end
+  end
+  return blocks
+end
+
+-- A block is runnable if it builds a client (sdk.new / sdk.test) or uses one
+-- (references \`client\`). These are the blocks we EXECUTE offline.
+local function is_runnable(block)
+  return block:find("sdk%s*%.%s*new") ~= nil
+    or block:find("sdk%s*%.%s*test") ~= nil
+    or block:find("client") ~= nil
+end
+
+-- NARROW illustration class:
+--   - a comment-only block (nothing remains after stripping lua comments), or
+--   - a --[[ ]] value-slot placeholder template (e.g. field = --[[ type ]]):
+--     the placeholder stands in for a value, so the block does not parse.
+-- Everything else must be runnable and is executed; a non-runnable,
+-- non-illustration block is a silently-untested example and fails the
+-- completeness gate.
+local function is_illustration(block)
+  local stripped = block:gsub("%-%-%[%[.-%]%]", "")  -- block comments
+  stripped = stripped:gsub("%-%-[^\\n]*", "")          -- line comments
+  if trim(stripped) == "" then
+    return true
+  end
+  if block:find("%-%-%[%[") and load(block) == nil then
+    return true
+  end
+  return false
+end
+
+-- Transform a README block into an executable offline snippet: rewrite any
+-- client constructor to the seeded test-mode form, inject a seeded client for
+-- bare fragments, and ensure \`sdk\` is in scope.
+local function make_runnable(block)
+  local src = block
+
+  local constructs = block:find("sdk%s*%.%s*new") ~= nil
+    or block:find("sdk%s*%.%s*test") ~= nil
+
+  if constructs then
+    -- %b() matches a balanced ( ... ) argument list, so nested tables/parens
+    -- in the original constructor call are replaced wholesale.
+    src = src:gsub("sdk%s*%.%s*new%s*%b()", function() return TEST_CTOR end)
+    src = src:gsub("sdk%s*%.%s*test%s*%b()", function() return TEST_CTOR end)
+  end
+
+  local prelude = {}
+  if not src:find("require%s*%(") then
+    table.insert(prelude, 'local sdk = require("' .. SDK_MODULE .. '")')
+  end
+  if not constructs and src:find("client") then
+    table.insert(prelude, "local client = " .. TEST_CTOR)
+  end
+
+  if #prelude > 0 then
+    src = table.concat(prelude, "\\n") .. "\\n" .. src
+  end
+  return src
+end
+
+-- All three docs are checked identically. relpath is resolved against this
+-- test file's directory (<repo>/lua/test).
+local DOCS = {
+  { label = "root README",   relpath = "../../README.md" },
+  { label = "lua/README",    relpath = "../README.md" },
+  { label = "lua/REFERENCE", relpath = "../REFERENCE.md" },
+}
+
+for _, doc in ipairs(DOCS) do
+  describe("lua doc examples (" .. doc.label .. ")", function()
+    local md = read_doc(doc.relpath)
+
+    it(doc.label .. " is present", function()
+      assert.is_not_nil(md, "could not read " .. doc.label ..
+        " (" .. doc.relpath .. ")")
+    end)
+
+    if not md then
+      return
+    end
+
+    local blocks = extract_blocks(md, "lua")
+
+    it(doc.label .. " has lua example blocks", function()
+      assert.is_true(#blocks > 0, "no lua code blocks found in " .. doc.label)
+    end)
+
+    it(doc.label .. ": every lua block is syntactically valid", function()
+      for i, block in ipairs(blocks) do
+        -- Illustration placeholders (--[[ type ]] templates) intentionally do
+        -- not parse; every other block must.
+        if not is_illustration(block) then
+          local chunk, err = load(block, "=" .. doc.label .. "-lua-" .. i)
+          assert.is_not_nil(chunk,
+            doc.label .. " lua block #" .. i .. " has a syntax error: " ..
+            tostring(err) .. "\\n----\\n" .. block .. "\\n----")
+        end
+      end
+    end)
+
+    it(doc.label .. ": every runnable lua block runs offline in test mode",
+      function()
+      local ran = 0
+      for i, block in ipairs(blocks) do
+        if is_runnable(block) and not is_illustration(block) then
+          local src = make_runnable(block)
+          local chunk, err = load(src, "=" .. doc.label .. "-run-" .. i)
+          assert.is_not_nil(chunk,
+            doc.label .. " runnable block #" .. i .. " failed to compile: " ..
+            tostring(err) .. "\\n----\\n" .. src .. "\\n----")
+          local ok, e = pcall(chunk)
+          if not ok then
+            local msg = tostring(e)
+            -- A nil accessor / missing method / bad index is a real doc bug:
+            -- the documented call does not exist.
+            if msg:find("nil value") or msg:find("attempt to call")
+              or msg:find("attempt to index") then
+              assert.is_true(false,
+                doc.label .. " runnable block #" .. i .. " hit a runtime " ..
+                "error (missing method / nil call): " .. msg ..
+                "\\n----\\n" .. src .. "\\n----")
+            end
+            -- Other runtime errors (a seeded-fixture miss surfaces as a
+            -- tolerated not-found domain error, e.g. "request: 404") are
+            -- expected offline and tolerated.
+          end
+          ran = ran + 1
+        end
+      end
+      assert.is_true(ran > 0,
+        "expected at least one runnable lua block in " .. doc.label)
+    end)
+
+    it(doc.label .. ": every lua block is executed or an explicit " ..
+      "illustration (completeness)", function()
+      local executed, illustration = 0, 0
+      local unclassified = {}
+      for i, block in ipairs(blocks) do
+        if is_illustration(block) then
+          illustration = illustration + 1
+        elseif is_runnable(block) then
+          executed = executed + 1
+        else
+          table.insert(unclassified, i)
+        end
+      end
+      assert.is_true(#unclassified == 0,
+        doc.label .. " has lua block(s) that are neither runnable nor a " ..
+        "recognized illustration and would be silently untested: #" ..
+        table.concat(unclassified, ", #"))
+      assert.are.equal(#blocks, executed + illustration,
+        doc.label .. " completeness: total " .. #blocks ..
+        " != executed " .. executed .. " + illustration " .. illustration)
+      print(string.format(
+        "[readme-lua] %s: total=%d executed=%d illustration=%d",
+        doc.label, #blocks, executed, illustration))
+    end)
+  end)
+end
+`)
+  })
+
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/lua/ReadmeHowto_lua.ts

@@ -1,12 +1,52 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+// A type-correct Lua literal for a field's canonical type.
+function luaLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k || 'OBJECT' === k) return '{}'
+  return '"example"'
+}
+
+function luaKey(name: string): string {
+  return /^[A-Za-z_]\w*$/.test(name) ? name : `["${name}"]`
+}
 
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  // Model-driven id key: null when the entity has no id-like field.
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  // Drive the test-mode example off the entity's PRIMARY op — never a hardcoded
+  // `load` a create-only entity lacks.
+  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testCallArg = ''
+  if (exampleEntity && isMatchOp) {
+    testCallArg = idF ? `{ ${idF} = "test01" }` : ''
+  } 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)
+    testCallArg = `{ ${chosen.map((it: any) => `${luaKey(it.name)} = ${luaLit(it.type)}`).join(', ')} }`
+  }
+
   const apikeyEnvLine = isAuthActive(model)
-    ? `\n${model.NAME}_APIKEY=<your-key>`
+    ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
 
   Content(`### Make a direct HTTP request
@@ -47,12 +87,10 @@ print(fetchdef["headers"])
 Create a mock client for unit testing — no server required:
 
 \`\`\`lua
-local client = sdk.test(nil, nil)
+local client = sdk.test()
 
-local result, err = client:${model.const.Name}(nil):load(
-  { id = "test01" }, nil
-)
--- result contains mock response data
+local result, err = client:${eName}():${primaryOp}(${testCallArg})
+-- result is the returned data; err is set on failure
 \`\`\`
 
 ### Use a custom fetch function
@@ -84,7 +122,7 @@ local client = sdk.new({
 Create a \`.env.local\` file at the project root:
 
 \`\`\`
-${model.NAME}_TEST_LIVE=TRUE${apikeyEnvLine}
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
 \`\`\`
 
 Then run:

package/project/.sdk/src/cmp/lua/ReadmeInstall_lua.ts

@@ -1,13 +1,14 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
 
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
-  Content(`\`\`\`bash
-luarocks install ${model.name}-sdk
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+${installCommand(model, target.name)}
 \`\`\`
 
 If the module is not yet published, add the source directory to
@@ -17,6 +18,21 @@ your \`LUA_PATH\`:
 export LUA_PATH="path/to/lua/?.lua;path/to/lua/?/init.lua;;"
 \`\`\`
 
+`)
+    return
+  }
+
+  // Publish pending: not yet on LuaRocks. Install from the git release tag,
+  // or add the source directory to LUA_PATH.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to LuaRocks. Install it from the
+GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})),
+or add the source directory to your \`LUA_PATH\`:
+
+\`\`\`bash
+export LUA_PATH="path/to/lua/?.lua;path/to/lua/?/init.lua;;"
+\`\`\`
+
 `)
 })
 

package/project/.sdk/src/cmp/lua/ReadmeIntro_lua.ts

@@ -1,13 +1,50 @@
 
 import { cmp, Content } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  // Derive a real entity accessor from the model for the semantic-entity
+  // note (fall back to a generic name if the model has no entities).
+  const entity = getModelPath(model, `main.${KIT}.entity`) || {}
+  const exampleEntity = Object.values(entity).find((e: any) => e && e.active !== false) as any
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
 
   Content(`# ${model.Name} ${target.title} SDK
 
-The ${target.title} SDK for the ${model.Name} API. Provides an entity-oriented interface using Lua conventions.
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client using Lua conventions.
+
+It exposes the API as capitalised, semantic **Entities** — e.g. \`client:${eName}()\` — each with the same small set of operations (${opList}) instead of raw URL paths and query strings. You call meaning, not endpoints, which keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
 
 `)
 })