@voxgig/sdkgen 3.5.1 → 3.7.0

package/src/utility.ts

@@ -6,6 +6,7 @@ import { JostracaResult, each } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
 
 import { serverVariables } from './helpers/serverVars'
+import { packageVersion } from './helpers/packageMeta'
 
 
 // Where a per-target component is loaded from: `<project>/.sdk/dist/<path>`.
@@ -290,7 +291,7 @@ function rawStringLiteral(s: string): string {
 //
 // Key order is `each`'s order, which is sorted, so the JSON is byte-stable
 // across runs exactly like the literal it replaces.
-function configDefinition(model: any): { def: any, json: string } {
+function configDefinition(model: any, targetname?: string): { def: any, json: string } {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
@@ -330,8 +331,22 @@ function configDefinition(model: any): { def: any, json: string } {
   options.headers = headers
   options.entity = entityStubs
 
+  // Identity beyond the camel Name: the hyphenated slug is CARRIED, never
+  // derived from the camel form downstream (deriving swallows hyphens - the
+  // packageMeta envToken defect), and version/target let a running SDK say
+  // what it is. Station's descriptor (voxgig/station) reads all three.
+  // Gated on targetname so a target that does not pass its name emits the
+  // exact config it always has - each target opts in when its literal
+  // emitter learns the fields too, keeping data and literal reps in step.
+  const main: any = { name: model.const.Name }
+  if (null != targetname) {
+    main.slug = model.name
+    main.version = packageVersion(model, targetname)
+    main.target = targetname
+  }
+
   const def = {
-    main: { name: model.const.Name },
+    main,
     feature: featureDefs,
     options,
     entity: entityDefs,

package/testkit.d.ts

@@ -0,0 +1,3 @@
+// Types for the `@voxgig/sdkgen/testkit` entry point. See testkit.js.
+
+export * from './dist/testkit'

package/testkit.js

@@ -0,0 +1,12 @@
+/* Copyright (c) 2024-2026 Voxgig Ltd, MIT License */
+
+// `require('@voxgig/sdkgen/testkit')` — the package's second entry point.
+//
+// A stub rather than an `exports` map entry, on purpose. A map would name
+// this subpath and, in doing so, replace the deep-import freedom this package
+// has without one — and consumers depend on that freedom invisibly (generated
+// model files include `@voxgig/sdkgen/model/sdkgen.aontu`; the scaffold is
+// reached as `@voxgig/sdkgen/project/<lang>`). See the `_no_exports_comment`
+// in package.json for what was measured.
+
+module.exports = require('./dist/testkit.js')

package/project/.sdk/model/target/haskell.aontu

@@ -1,72 +0,0 @@
-
-main: kit: target: haskell: {
-
-  title: Haskell
-  ext: hs
-  comment: line: "--"
-  module: name: '$$name$$'
-  base: 'BASE'
-  srcfeature: false
-
-  # Entities are generic (config-driven F.makeEntity), so no per-entity or
-  # per-feature generated modules. The readme + agentguide phases are
-  # model-driven (they read the API model directly, not per-entity generated
-  # code), so they are active and produce the docs; entity/feature generation
-  # stays off.
-  phase: {
-    entity:     { active: false }
-    feature:    { active: false }
-    readme:     { active: true }
-    agentguide: { active: true }
-    test:       { active: true }
-  }
-
-  deps: &: {
-    kind: *'prod' | string
-  }
-
-  # struct is vendored under src/ (VoxgigStruct.hs + Vregex.hs) — the runtime
-  # is dependency-free: it compiles with the stock ghc (base + containers, the
-  # GHC boot libraries), no cabal packages, no stack. So there are no manifest
-  # dependencies.
-  deps: {}
-}
-
-
-main: kit: feature: &: target: haskell: deps: &: {
-  kind: *'prod' | string
-}
-
-
-# Publication: Hackage registry (declared, publish pending — git-tag only).
-#
-# `target add <t>` OVERWRITES this file, so a project must never set its
-# publication values here — voxgig-solardemo-sdk lost its pinned npm package
-# name exactly that way. Set them in the project's own model
-# (`model/sdk.aontu`), where they survive a resync.
-#
-# For that to work this file must LEAVE THOSE KEYS UNSET: in aontu a concrete
-# value does not yield to another concrete value, it CONFLICTS, and two
-# defaults conflict too. The schema (@voxgig/sdkgen/model/sdkgen.aontu)
-# already defaults `tag.active`, `registry.state`, `registry.active` and
-# `registry.package`, so a project's concrete value wins over the default and
-# repeating them here would only take that away.
-#
-# What remains below is per-target registry IDENTITY, which is not a project
-# choice and stays concrete.
-main: kit: target: haskell: publish: {
-  registry: {
-    name: 'hackage'
-    url: 'https://hackage.haskell.org'
-    vault: { alias: 'hackage', env: 'HACKAGE_TOKEN' }
-  }
-}
-
-
-# Feature source is NOT trimmed to the model's selection here: every
-# feature lives inside a single generated module (src/SdkFeatures.hs), not
-# in per-feature source files, so there is nothing per-feature to leave
-# out. Trimming waits on that module becoming model-driven.
-main: kit: target: haskell: feature: {
-  trim: false
-}

package/project/.sdk/src/cmp/haskell/Config_haskell.ts

@@ -1,98 +0,0 @@
-import {
-  Content,
-  File,
-  cmp,
-  configDefinition,
-  configReprSetting,
-  isConfigData,
-} from '@voxgig/sdkgen'
-
-
-import {
-  Model,
-} from '@voxgig/apidef'
-
-
-import {
-  formatHsValue,
-  hsString,
-} from './utility_haskell'
-
-
-// The full set of feature constructors in SdkFeatures (name -> <name>Feature).
-const FEATURE_NAMES = [
-  'log', 'test', 'retry', 'timeout', 'ratelimit', 'cache', 'idempotency',
-  'paging', 'streaming', 'proxy', 'telemetry', 'metrics', 'debug', 'audit',
-  'clienttrack', 'rbac', 'netsim',
-]
-
-
-// SdkConfig.hs: makeConfig builds the embedded API model as a struct Value;
-// makeFeature(name) is the N-feature-safe factory the client uses to
-// instantiate features named in the options.
-const Config = cmp(async function Config(props: any) {
-  const ctx$ = props.ctx$
-  const target = props.target
-
-  const model: Model = ctx$.model
-
-  // The same config as an OBJECT, built by the shared helper so this target's
-  // literal and the data that replaces it above the threshold are the same
-  // config by construction. The JSON is what the threshold is measured on -
-  // emitted source size varies by language, the model does not.
-  const { def: configDef, json: configJson } = configDefinition(model)
-  const asData = isConfigData(configJson, configReprSetting(model))
-
-  // ABOVE THE THRESHOLD: emit the model as DATA.
-  //
-  // The literal representation is one enormous CV expression. GHC type-checks
-  // and desugars every constructor application in it, and buildCV then walks
-  // the whole tree allocating an IORef per node. A string constant is one
-  // token, and jsonRead builds the same Value from it directly.
-  //
-  // Both branches return a FRESH Value per call - buildCV allocates new
-  // IORefs, jsonRead re-parses - so a caller that mutates one config cannot
-  // reach another's, exactly as before.
-  const configBody = asData
-    ? `-- THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
---
--- Emitted only above a size threshold, or when \`main.kit.config.repr\` pins
--- it: for a small model the CV literal is smaller and far easier to read when
--- debugging.
-configData :: String
-configData = ${hsString(configJson)}
-
-makeConfig :: IO Value
-makeConfig = jsonRead configData`
-    : `makeConfig :: IO Value
-makeConfig = buildCV ${formatHsValue(configDef)}`
-
-  File({ name: 'SdkConfig.' + target.ext }, () => {
-
-    Content(`-- Generated API configuration (make_config) and the feature factory.
-
-module SdkConfig (makeConfig, makeFeature) where
-
-import VoxgigStruct (Value)
-import ${asData ? 'SdkJson (jsonRead)' : 'SdkHelpers (CV (..), buildCV)'}
-import SdkTypes (Feature)
-import qualified SdkFeatures as F
-
-${configBody}
-
-makeFeature :: String -> IO Feature
-makeFeature name = case name of
-`)
-
-    for (const fname of FEATURE_NAMES) {
-      Content(`  "${fname}" -> F.${fname}Feature\n`)
-    }
-
-    Content(`  _ -> F.baseFeature\n`)
-  })
-})
-
-
-export {
-  Config
-}

package/project/.sdk/src/cmp/haskell/Entity_haskell.ts

@@ -1,13 +0,0 @@
-import { cmp } from '@voxgig/sdkgen'
-
-
-// Entities are generic in the Haskell target: there is no per-entity
-// generated module. Every entity is created by the config-driven
-// F.makeEntity (see SdkClient), so this component emits nothing. It exists
-// only so the neutral Entity component can resolve a language delegate.
-const Entity = cmp(function Entity(_props: any) {})
-
-
-export {
-  Entity
-}

package/project/.sdk/src/cmp/haskell/Gitignore_haskell.ts

@@ -1,27 +0,0 @@
-import {
-  Content,
-  File,
-  cmp,
-} from '@voxgig/sdkgen'
-
-
-const Gitignore = cmp(async function Gitignore(_props: any) {
-  File({ name: '.gitignore' }, () => {
-    Content(`# Haskell build output
-.hsbuild/
-dist-newstyle/
-*.hi
-*.o
-
-# IDE / OS
-.idea/
-.vscode/
-.DS_Store
-`)
-  })
-})
-
-
-export {
-  Gitignore
-}

package/project/.sdk/src/cmp/haskell/Main_haskell.ts

@@ -1,123 +0,0 @@
-import {
-  cmp, each,
-  File, Content, Copy, Folder,
-} from '@voxgig/sdkgen'
-
-
-import type {
-  ModelEntity
-} from '@voxgig/apidef'
-
-
-import {
-  KIT,
-  getModelPath
-} from '@voxgig/apidef'
-
-
-import { Package } from './Package_haskell'
-import { Config } from './Config_haskell'
-import { Gitignore } from './Gitignore_haskell'
-import { hsVarName } from './utility_haskell'
-
-
-const Main = cmp(async function Main(props: any) {
-
-  const { target } = props
-  const { model } = props.ctx$
-
-  const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-
-  Package({ target })
-
-  Gitignore({})
-
-  // Copy tm/haskell verbatim: the runtime under src/ (VoxgigStruct, Vregex,
-  // SdkTypes, SdkHelpers, SdkRuntime, SdkFeatures), the test suite under
-  // test/, and Makefile/LICENSE/VERSION. The per-feature custom-source
-  // scaffold under src/feature is excluded (this target does not use it —
-  // entities are generic and config-driven, so there are no per-entity or
-  // per-feature generated modules). Placeholder substitution applies.
-  Copy({
-    from: 'tm/' + target.name,
-    exclude: [/src\/feature\//],
-    replace: {
-      ...props.ctx$.stdrep,
-    }
-  })
-
-  // Generated modules under src/: the API config + feature factory, and the
-  // public client (SDK constructors + entity accessors).
-  Folder({ name: 'src' }, () => {
-
-    Config({ target })
-
-    File({ name: 'SdkClient.' + target.ext }, () => {
-
-      let accessors = ''
-      let exports = ''
-      each(entity, (e: any) => {
-        const fn = hsVarName(e.name)
-        exports += `  , ${fn}\n`
-        accessors += `-- | The ${e.Name} entity bound to this client.
-${fn} :: Client -> Value -> IO Entity
-${fn} client entopts = F.makeEntity client "${e.name}" entopts
-
-`
-      })
-
-      Content(`-- ${model.const.Name} SDK public client (generated by @voxgig/sdkgen).
---
--- SDK constructors (newSdk / testSdk) and one accessor per entity. Entities
--- are generic — every accessor calls the config-driven F.makeEntity, so the
--- operation pipeline is identical for every entity and every API.
-
-module SdkClient
-  ( module SdkTypes
-  , newSdk
-  , newSdk0
-  , testSdk
-  , testSdk0
-${exports}  ) where
-
-import Data.IORef (readIORef)
-
-import VoxgigStruct (Value (..))
-import SdkTypes
-import SdkConfig (makeConfig, makeFeature)
-import qualified SdkFeatures as F
-
--- | Construct a live SDK client from an options map (Noval for defaults).
-newSdk :: Value -> IO Client
-newSdk options = do
-  cfg <- makeConfig
-  F.makeClientBase cfg makeFeature options
-
--- | No-argument convenience constructor.
-newSdk0 :: IO Client
-newSdk0 = newSdk VNoval
-
--- | Construct a test-mode SDK: testSdk testopts sdkopts.
-testSdk :: Value -> Value -> IO Client
-testSdk testopts sdkopts = do
-  cfg <- makeConfig
-  F.sdkTest cfg makeFeature testopts sdkopts
-
--- | No-argument convenience test constructor.
-testSdk0 :: IO Client
-testSdk0 = testSdk VNoval VNoval
-
--- | The active client mode ("live" or "test").
-clientMode :: Client -> IO String
-clientMode = readIORef . clMode
-
-${accessors}`)
-    })
-  })
-
-})
-
-
-export {
-  Main
-}

package/project/.sdk/src/cmp/haskell/Package_haskell.ts

@@ -1,60 +0,0 @@
-import {
-  Content,
-  File,
-  cmp,
-  packageVersion,
-} from '@voxgig/sdkgen'
-
-
-import type {
-  Model,
-} from '@voxgig/apidef'
-
-
-function pkgName(model: any): string {
-  const org = (model.origin || 'voxgig-sdk').replace(/-sdk$/, '')
-  return `${org}-${model.name}-sdk`.toLowerCase().replace(/[^a-z0-9-]/g, '-')
-}
-
-
-// The cabal package file (for Hackage publication). The offline test build
-// uses the Makefile (stock ghc, boot libraries only: base + containers +
-// array + time), so no cabal solve is required to run the suite.
-const Package = cmp(async function Package(props: any) {
-  const ctx$ = props.ctx$
-  const target = props.target
-
-  const model: Model = ctx$.model
-
-  File({ name: pkgName(model) + '.cabal' }, () => {
-    Content(`cabal-version:      2.4
-name:               ${pkgName(model)}
-version:            ${packageVersion(model, target.name)}
-synopsis:           ${model.const.Name} SDK for Haskell (generated by @voxgig/sdkgen)
-license:            MIT
-build-type:         Simple
-
-library
-    default-language: Haskell2010
-    hs-source-dirs:   src
-    exposed-modules:  VoxgigStruct
-                      Vregex
-                      SdkJson
-                      SdkTypes
-                      SdkHelpers
-                      SdkRuntime
-                      SdkFeatures
-                      SdkConfig
-                      SdkClient
-    build-depends:    base >=4.14 && <5
-                    , containers >=0.6 && <0.8
-                    , array >=0.5 && <0.6
-                    , time >=1.9 && <1.15
-`)
-  })
-})
-
-
-export {
-  Package
-}

package/project/.sdk/src/cmp/haskell/ReadmeEntity_haskell.ts

@@ -1,186 +0,0 @@
-
-import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
-
-import {
-  KIT,
-  getModelPath,
-} from '@voxgig/apidef'
-
-import { hsVarName } from './utility_haskell'
-
-
-// A type-correct Haskell `Value` literal for a field's canonical type.
-function hsLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
-  if ('INTEGER' === k || 'NUMBER' === k) return 'VNum 1'
-  if ('BOOLEAN' === k) return 'VBool True'
-  if ('ARRAY' === k || 'OBJECT' === k) return 'VNoval'
-  return `VStr "${placeholder}"`
-}
-
-
-// A readable Haskell type name for a field's canonical type. The runtime
-// carries every field as a dynamic `Value`; this documents the logical type.
-function hsType(type: any): string {
-  const k = canonKey(type)
-  if ('STRING' === k) return 'String'
-  if ('INTEGER' === k) return 'Int'
-  if ('NUMBER' === k) return 'Double'
-  if ('BOOLEAN' === k) return 'Bool'
-  if ('ARRAY' === k) return '[Value]'
-  return 'Value'
-}
-
-
-const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'eLoad ent match ctrl',   desc: 'Load a single entity by match criteria. Resolves to the entity.' },
-  list:   { method: 'eList ent match ctrl',   desc: 'List entities, optionally matching the given criteria. Resolves to one entity per record.' },
-  create: { method: 'eCreate ent data ctrl',  desc: 'Create a new entity with the given data. Resolves to the entity.' },
-  update: { method: 'eUpdate ent data ctrl',  desc: 'Update an existing entity. Resolves to the entity.' },
-  remove: { method: 'eRemove ent match ctrl', desc: 'Remove the matching entity. Resolves to the entity, marked deleted.' },
-}
-
-
-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 || []
-    const idF = entityIdField(entity)
-    const eFn = hsVarName(entity.name)
-
-    Content(`
-### ${entity.Name}
-
-`)
-
-    if (entity.short) {
-      Content(`${entity.short}
-
-`)
-    }
-
-    Content(`Create an instance: \`${eFn} <- Sdk.${eFn} sdk VNoval\`
-
-`)
-
-    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}\` | \`${hsType(field.type)}\` | ${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
-        ? `[${loadItems.map((it: any) =>
-          `("${it.name}", ${hsLit(it.type,
-            it.name === idF ? entity.name + '_id' : it.name)})`).join(', ')}]`
-        : '[]'
-      Content(`#### Example: Load
-
-\`\`\`haskell
-  ent <- Sdk.${eFn} sdk VNoval
-  match <- jo ${loadArg}
-  ctrl <- emptyMap
-  ${eFn} <- Sdk.eLoad ent match ctrl
-  -- The op resolves to the ENTITY; the record is inside it.
-  ${eFn}Data <- Sdk.eDataGet ${eFn}
-\`\`\`
-
-`)
-    }
-
-    if (opnames.includes('list')) {
-      Content(`#### Example: List
-
-\`\`\`haskell
-  ent <- Sdk.${eFn} sdk VNoval
-  match <- emptyMap
-  ctrl <- emptyMap
-  -- One ENTITY per record.
-  ${eFn}s <- Sdk.eList ent match ctrl
-  ${eFn}Datas <- mapM Sdk.eDataGet ${eFn}s
-\`\`\`
-
-`)
-    }
-
-    if (opnames.includes('create')) {
-      const createItems = opRequestShape(entity, 'create').items
-        .filter((it: any) => !it.optional)
-      Content(`#### Example: Create
-
-\`\`\`haskell
-  ent <- Sdk.${eFn} sdk VNoval
-  d <- jo
-    [`)
-      createItems.map((it: any, i: number) => {
-        const bracket = 0 === i ? ' ' : ', '
-        Content(`${bracket}("${it.name}", ${hsLit(it.type, 'example_' + it.name)})   -- ${hsType(it.type)}
-    `)
-      })
-      Content(`]
-  ctrl <- emptyMap
-  ${eFn} <- Sdk.eCreate ent d ctrl
-  ${eFn}Data <- Sdk.eDataGet ${eFn}
-\`\`\`
-
-`)
-    }
-  })
-})
-
-
-export {
-  ReadmeEntity
-}