@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/go/EntityTypes_go.ts

@@ -27,11 +27,11 @@
 //     with every field optional (Go's analog of TS `Partial<Name>`).
 
 import {
-  cmp, each, names,
+  cmp, each,
   File, Content, Folder,
 } from '@voxgig/sdkgen'
 
-import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -62,32 +62,127 @@ function goField(name: string): string {
 }
 
 
+// The json struct tag is the WIRE CONTRACT: it decides the key requests
+// marshal under and the key responses populate from.
+//
+// Can this spec-derived name be carried in a Go json struct tag AT ALL?
+//
+// It cannot always be. `encoding/json`'s isValidTag accepts letters, digits and
+// a fixed punctuation set; a name containing a double quote, a backtick or a
+// backslash is REJECTED, and Go then silently falls back to the Go FIELD name.
+// Verified against go1.24 — for a field named `na"me`:
+//
+//   raw literal      `json:"na"me"`        -> marshals as {"na": ...}   (truncated)
+//   escaped literal  "json:\"na\\\"me\""   -> marshals as {"NaMe": ...} (tag ignored)
+//
+// So there is no encoding that preserves such a name. An earlier version here
+// stripped the offending characters, which is worse than either: it silently
+// changed the wire contract, marshalling under a key the API never uses and
+// never populating from the real response key. Names that cannot be
+// represented are skipped with a warning instead — the same treatment
+// csharp/java give names with no legal identifier form.
+const GO_TAG_PUNCT = '!#$%&()*+-./:;<=>?@[]^_{|}~ '
+
+function goTaggable(name: string): boolean {
+  const s = String(name)
+  if ('' === s) {
+    return false
+  }
+  for (const c of s) {
+    if (GO_TAG_PUNCT.includes(c)) continue
+    if (/[\p{L}\p{Nd}]/u.test(c)) continue
+    return false
+  }
+  return true
+}
+
+
+function goTag(name: string, omitempty: boolean): string {
+  const jsonName = String(name) + (omitempty ? ',omitempty' : '')
+  return '`json:"' + jsonName + '"`'
+}
+
+
 // One Go struct field line. `optional` -> pointer + ,omitempty (Go's closest
-// analog to an optional/absent field).
-function fieldLine(name: string, sentinel: any, optional: boolean): string {
+// analog to an optional/absent field). `ident` overrides the derived field
+// identifier when goField() would collide with a sibling (see uniqueGoFields).
+function fieldLine(name: string, sentinel: any, optional: boolean, ident?: string): string {
   const gt = canonToType(sentinel, LANG)
   const typ = optional ? ('*' + gt) : gt
-  const tag = optional ? `\`json:"${name},omitempty"\`` : `\`json:"${name}"\``
-  return `\t${goField(name)} ${typ} ${tag}\n`
+  return `\t${ident || goField(name)} ${typ} ${goTag(name, optional)}\n`
 }
 
 
+// Collision-free Go field identifiers for one struct's members.
+//
+// goField() is lossy — it strips every non-alphanumeric character — so
+// `some_field`, `some-field` and `someField` all map to `SomeField`. Emitting
+// them into the same struct is a "field redeclared" compile error, and Go is
+// the only target exposed to it (ts/py/… keep the raw key). Later duplicates
+// get a numeric suffix; the FIRST occurrence keeps the natural name, and the
+// json tag always keeps the original wire name, so behaviour is unchanged.
+// Deterministic: members arrive in sorted-key order from opRequestShape/each.
+function uniqueGoFields(members: { name: string }[]): string[] {
+  const taken: Record<string, boolean> = {}
+  return members.map((m) => {
+    const base = goField(m.name)
+    let ident = base
+    let n = 1
+    while (taken[ident]) {
+      n++
+      ident = base + n
+    }
+    taken[ident] = true
+    return ident
+  })
+}
+
+
+// Keep a member only when its name survives into a Go json tag; warn once per
+// dropped member so the omission is visible rather than a silent contract change.
+function skipUntaggable(member: any, typeName: string, log: any): boolean {
+  if (null == member || null == member.name) {
+    return false
+  }
+  if (goTaggable(member.name)) {
+    return true
+  }
+  if (log && log.warn) {
+    log.warn({
+      point: 'entity-types-skip-field', typeName, field: member.name,
+      note: `go: field "${member.name}" of ${typeName} cannot be carried in a ` +
+        `Go json struct tag (encoding/json rejects the name, and Go would ` +
+        `silently marshal under the field name instead); omitted from the ` +
+        `typed model (still reachable via the runtime map)`,
+    })
+  }
+  return false
+}
+
+
+
 const EntityTypes = cmp(function EntityTypes(props: any) {
   const { target } = props
-  const { model } = props.ctx$
+  const { model, log } = props.ctx$
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // 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 file. Main_go.ts / Entity_go.ts
   // iterate entities WITHOUT an `active` filter and reference the typed data
   // type `<Name>` in every *_entity.go, so a struct is required for each or the
-  // package won't compile. Filter on `name` (always present), NOT `Name`:
-  // `Name` is the PascalCase variant derived LAZILY by `names()`, so filtering
-  // on it silently drops any entity whose `Name` hasn't been derived yet by an
-  // earlier component (order-dependent — e.g. fieldless placeholder entities),
-  // producing `undefined: <Name>` in the generated Go. Derive `Name` here so
-  // the struct set is deterministic and matches the *_entity.go set.
-  const entityList = each(entity).filter((e: any) => e && null != e.name)
-  entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+  // package won't compile. deriveEntityNames() selects on `name` (always
+  // present) and derives the lazily-set PascalCase `Name` up front, so the
+  // struct set is deterministic and matches the *_entity.go set regardless of
+  // which component runs first.
+  const entityList = deriveEntityNames(entity)
+
+  // 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: 'entity' }, () => {
 
@@ -114,8 +209,11 @@ import "encoding/json"
         Content(`// ${Name} is the typed data model for the ${ent.name} entity.
 type ${Name} struct {
 `)
-        fields.forEach((f: any) => {
-          Content(fieldLine(f.name, f.type, false === f.req))
+        const taggable = fields.filter(
+          (f: any) => skipUntaggable(f, Name, log))
+        const fieldIdents = uniqueGoFields(taggable)
+        taggable.forEach((f: any, i: number) => {
+          Content(fieldLine(f.name, f.type, false === f.req, fieldIdents[i]))
         })
         Content(`}
 
@@ -137,8 +235,11 @@ type ${Name} struct {
           Content(`// ${typeName} is the typed request payload for ${Name}.${cap(opname)}Typed.
 type ${typeName} struct {
 `)
-          items.forEach((it: any) => {
-            Content(fieldLine(it.name, it.type, it.optional))
+          const taggableItems = items.filter(
+            (it: any) => skipUntaggable(it, typeName, log))
+          const itemIdents = uniqueGoFields(taggableItems)
+          taggableItems.forEach((it: any, i: number) => {
+            Content(fieldLine(it.name, it.type, it.optional, itemIdents[i]))
           })
           Content(`}
 

package/project/.sdk/src/cmp/go/Entity_go.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, camelify, names,
   File, Content, Folder, Fragment, Line, FeatureHook, Slot,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 import {
@@ -26,7 +26,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. The DATA type stays `<Name>`.
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -42,7 +42,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: entity.name + '_entity.' + 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 static

package/project/.sdk/src/cmp/go/Main_go.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -19,6 +19,7 @@ import {
 } from '@voxgig/apidef'
 
 
+import { goFeatureName } from './utility_go'
 import { Package } from './Package_go'
 import { Config } from './Config_go'
 import { Gitignore } from './Gitignore_go'
@@ -82,7 +83,7 @@ const Main = cmp(async function Main(props: any) {
 
             '#BuildFeatures': ({ indent }: any) => {
               each(feature, (feat: any) => {
-                const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+                const fname = goFeatureName(feat)
                 Content({ indent }, `u.FeatureAdd(s.rootctx, New${fname}FeatureFunc())
 `)
               })
@@ -119,7 +120,7 @@ var NewBaseFeatureFunc func() Feature
       // Feature constructor function vars (non-base)
       each(feature, (feat: any) => {
         if (feat.name !== 'base') {
-          const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+          const fname = goFeatureName(feat)
           Content(`var New${fname}FeatureFunc func() Feature
 
 `)
@@ -177,7 +178,7 @@ func init() {
     // Register non-base feature constructors
     each(feature, (feat: any) => {
       if (feat.name !== 'base') {
-        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        const fname = goFeatureName(feat)
         Content(`	core.New${fname}FeatureFunc = func() core.Feature {
 		return feature.New${fname}Feature()
 	}
@@ -188,7 +189,7 @@ func init() {
     // Register entity constructors
     each(entity, (ent: any) => {
       Content(`	core.New${ent.Name}EntityFunc = func(client *core.${model.const.Name}SDK, entopts map[string]any) core.${model.const.Name}Entity {
-		return entity.New${entityClassName(ent, entity)}(client, entopts)
+		return entity.New${entityClassName(ent, entityCollection(model))}(client, entopts)
 	}
 `)
     })
@@ -219,7 +220,7 @@ func Test() *${model.const.Name}SDK { return TestSDK(nil, nil) }
 
     each(feature, (feat: any) => {
       if (feat.name !== 'base') {
-        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        const fname = goFeatureName(feat)
         Content(`var New${fname}Feature = feature.New${fname}Feature
 `)
       }

package/project/.sdk/src/cmp/go/Package_go.ts

@@ -31,7 +31,7 @@ go 1.20
 
     const deps: Record<string, string> = {}
     const replaceDirs: Record<string, string> = {}
-    for (const d of collectDeps(model, target.name, target.deps)) {
+    for (const d of collectDeps(model, target.name, target.deps, ctx$.log)) {
       // Target-level deps default to 'v0.0.0' when version is absent;
       // feature deps require an explicit version.
       deps[d.name] = d.source === 'target' ? (d.version || 'v0.0.0') : d.version

package/project/.sdk/src/cmp/go/ReadmeHowto_go.ts

@@ -45,7 +45,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
-    testArg = idF ? `map[string]any{"${idF}": "test01"}` : 'nil'
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => !it.optional || it.name === idF)
+      .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+    testArg = 0 < items.length
+      ? `map[string]any{${items.map((it: any) => `"${it.name}": ${it.name === idF ? '"test01"' : goLit(it.type)}`).join(', ')}}`
+      : 'nil'
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')

package/project/.sdk/src/cmp/go/TestDirect_go.ts

@@ -75,7 +75,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? `\n\t\t\t"apikey": env["${PROJECTNAME}_APIKEY"],`
     : ''
 
-  const opnames = Object.keys(entity.op)
+  const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
 
@@ -83,8 +83,8 @@ const TestDirect = cmp(function TestDirect(props: any) {
     return
   }
 
-  const loadOp = entity.op.load
-  const listOp = entity.op.list
+  const loadOp = entity.op?.load
+  const listOp = entity.op?.list
 
   // Get load point info
   const loadPoint = loadOp?.points?.[0]

package/project/.sdk/src/cmp/go/TestEntity_go.ts

@@ -24,6 +24,7 @@ import {
   buildIdNames,
   getMatchEntries,
   isAuthActive,
+  entityDataIdField,
 } from '@voxgig/sdkgen'
 
 
@@ -58,7 +59,7 @@ const TestEntity = cmp(function TestEntity(props: any) {
   // it only applies to entities that declare a list op. Others (e.g. Batch =
   // create/load) have no list endpoint — make_point errors and the stream
   // yields nothing — so skip the stream test for them.
-  const hasList = !!(entity.op && (entity.op as any).list)
+  const hasList = !!(entity.op && (entity.op as any)?.list)
 
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
@@ -396,6 +397,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
 const generateList: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
+  const hasDataId = null != entityDataIdField(entity)
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = goVar(step.input.entvar ?? ref + '_ent')
   const matchvar = goVar(step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? '')))
@@ -431,7 +433,9 @@ const generateList: OpGen = (ctx, step, index) => {
   // Only declare ${listvar} as a real var when a downstream validator
   // actually uses it; otherwise `_` to satisfy Go's unused-var check.
   const allSteps = Object.values(flow.step) as any[]
-  const listvarUsed = !!step.valid?.some((v: any) => {
+  // hasDataId: the ItemExists/ItemNotExists asserts (the only listvar users) are
+  // now gated on a real DATA id field, so without one the list result is unused.
+  const listvarUsed = hasDataId && !!step.valid?.some((v: any) => {
     if ('ItemExists' !== v.apply && 'ItemNotExists' !== v.apply) return false
     const validRef = v.def?.ref
     return validRef && allSteps.some((s: any) => 'create' === s.op &&
@@ -460,7 +464,7 @@ const generateList: OpGen = (ctx, step, index) => {
       const hasRefData = validRef && allSteps.some((s: any) => 'create' === s.op &&
         ((s.input.ref ?? entity.name + '_ref01') === validRef))
 
-      if ('ItemExists' === validator.apply && hasRefData) {
+      if ('ItemExists' === validator.apply && hasRefData && hasDataId) {
         const refDataVar = goVar(validRef + '_data')
         Content(`
 		foundItem := vs.Select(entityListToData(${listvar}), map[string]any{"id": ${refDataVar}["id"]})
@@ -468,7 +472,7 @@ const generateList: OpGen = (ctx, step, index) => {
 			t.Fatal("expected to find created entity in list")
 		}
 `)
-      } else if ('ItemNotExists' === validator.apply && hasRefData) {
+      } else if ('ItemNotExists' === validator.apply && hasRefData && hasDataId) {
         const refDataVar = goVar(validRef + '_data')
         Content(`
 		notFoundItem := vs.Select(entityListToData(${listvar}), map[string]any{"id": ${refDataVar}["id"]})
@@ -642,6 +646,9 @@ const generateLoad: OpGen = (ctx, step, index) => {
 
 const generateRemove: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
+  if (null == entityDataIdField(entity)) {
+    return
+  }
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = goVar(step.input.entvar ?? ref + '_ent')
   const matchvar = goVar(step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? '')))

package/project/.sdk/src/cmp/go/utility_go.ts

@@ -6,7 +6,8 @@ import {
   camelify,
   canonKey,
   each,
-  safeVarName,
+  exampleVarName,
+  names,
 } from '@voxgig/sdkgen'
 
 import {
@@ -77,7 +78,8 @@ function exampleValue(entity: any, op: any, paramName: string, placeholder: stri
 // `type`/`range` entity must not bind a Go keyword).
 function goVarName(name: string): string {
   const pascal = camelify(name)
-  return safeVarName(pascal.charAt(0).toLowerCase() + pascal.slice(1), 'go')
+  // exampleVarName also guards `client`, the doc examples' SDK-instance var.
+  return exampleVarName(pascal.charAt(0).toLowerCase() + pascal.slice(1), 'go')
 }
 
 
@@ -148,7 +150,31 @@ function clean(o: any) {
 }
 
 
+
+// The Go identifier fragment for a feature's generated constructor
+// (New<Fname>Feature / New<Fname>FeatureFunc).
+//
+// SHARED because the identifier is DECLARED in Main_go.ts (registry.go and the
+// root init()) and REFERENCED in Config_go.ts (makeFeature). Two copies of the
+// derivation is a latent undefined-identifier bug in the generated SDK: they
+// were both `name.charAt(0).toUpperCase() + name.slice(1)`, consistently wrong
+// for a name needing real normalisation but at least agreeing, until one side
+// was fixed alone and `rate_limit` became NewRateLimitFeatureFunc in the
+// registry and NewRate_limitFeatureFunc in config.
+//
+// Uses the jostraca-derived PascalCase `Name` (deriving it if absent), which is
+// what Main_ts.ts uses, so a hyphenated or underscored feature name yields a
+// legal Go identifier instead of `NewRate-limitFeatureFunc`.
+function goFeatureName(feat: any): string {
+  if (null == feat.Name) {
+    names(feat, feat.name)
+  }
+  return feat.Name
+}
+
+
 export {
+  goFeatureName,
   clean,
   exampleValue,
   formatGoMap,