@voxgig/sdkgen 2.0.2 → 3.1.0

package/src/helpers/packageMeta.ts

@@ -14,6 +14,8 @@
 // Every value here is derived from the resolved model (model.name, model.origin,
 // main.kit.info.title) — no new inputs required.
 
+import { each } from 'jostraca'
+
 import { KIT, nom } from '@voxgig/apidef'
 
 const PUBLISHER = 'Voxgig'
@@ -38,15 +40,42 @@ function langLabel(target: string): string {
   return LANG_LABEL[target] || target
 }
 
-// GitHub org (publisher slug), repo name, and the canonical repo URLs.
+// Git host, org/repo path, and the canonical repo URLs.
+//
+// `<origin>/<slug>-sdk` is a DERIVATION, not a law. A project whose repo is
+// named anything else — `voxgig-sdk/voxgig-solardemo-sdk`, say, where the slug
+// is `solardemo` — used to have no way to say so, and got a `go.mod` module
+// path that 404s on `go get` plus `homepage`/`repository`/`bugs` URLs pointing
+// at a repo that does not exist. The only escape was renaming the slug, which
+// also renames the SDK classes: a public-API break, and no help at all to a
+// project that has already published.
+//
+//   main: kit: repo: {
+//     path: 'voxgig-sdk/voxgig-solardemo-sdk'   # overrides <origin>/<slug>-sdk
+//     host: 'github.com'                        # default
+//   }
 function repoInfo(model: any) {
   const slug = model.name
   const origin = model.origin || 'voxgig-sdk'
-  const repo = `${slug}-sdk`
-  const repoUrl = `https://github.com/${origin}/${repo}`
+
+  const declared = (model && model.main && model.main[KIT] && model.main[KIT].repo) || {}
+
+  const host = '' === (declared.host || '') ? 'github.com' : (declared.host || 'github.com')
+  const path = '' === (declared.path || '') ? `${origin}/${slug}-sdk` : String(declared.path)
+
+  // Last segment is the repo; everything before it is the org (which may
+  // itself contain slashes on hosts that allow subgroups, e.g. GitLab).
+  const seg = path.split('/')
+  const repo = seg[seg.length - 1]
+
+  const repoUrl = `https://${host}/${path}`
+
   return {
     slug,
     origin,
+    host,
+    // 'org/repo' — the path under the host, and the base of a go module path.
+    path,
     repo,
     repoUrl,
     issuesUrl: `${repoUrl}/issues`,
@@ -58,6 +87,94 @@ function repoInfo(model: any) {
 }
 
 
+// The go module path for a go-family target: the declared override, else the
+// repo path plus the target's subdirectory.
+//
+//   main: kit: target: go: module: path: 'github.com/acme/legacy-sdk/go'
+//
+// THE ONLY implementation. Twelve go components used to re-derive
+// `github.com/${origin}/${name}-sdk/go` inline, so fixing the path in one
+// place fixed nothing — and `ReadmeTop`, which prints the module in the root
+// README's package table, lives inside node_modules where a consumer cannot
+// patch it at all.
+function goModule(model: any, target: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.module?.path
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+
+  const { host, path } = repoInfo(model)
+  return `${host}/${path}/${target}`
+}
+
+
+// The SDK's OWN release version, for this target's manifest and release tag.
+//
+//   main: kit: target: ts: publish: version: '0.0.2'
+//
+// Defaults to '0.0.1' (the schema default), which is what every manifest
+// emitter used to HARDCODE. That is why regeneration reset a published
+// version: the value lived only in the generated output, so overwriting the
+// output threw it away, and a project that had shipped 0.0.2 silently got a
+// 0.0.1 manifest back. Declaring it in the model makes the manifest, the
+// install docs and the port's VERSION file agree, and survive.
+function packageVersion(model: any, target: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.publish?.version
+  return null != declared && '' !== declared ? String(declared) : '0.0.1'
+}
+
+
+// The Go language version for a go-family target's go.mod.
+//
+//   main: kit: target: go: module: goversion: '1.23'
+//
+// Defaults to 1.21, the release that introduced `log/slog` — which sdkgen's
+// own `log` feature template imports. The previous hardcoded `go 1.20` meant a
+// generated SDK could not compile the feature source sdkgen had just written
+// into it.
+function goVersion(model: any, target: string, fallback?: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.module?.goversion
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+  return fallback || '1.21'
+}
+
+
+// The root Go package IDENTIFIER — `package voxgigsolardemosdk`. Go requires
+// a plain identifier here, so unlike the module path it must be concatenated
+// from the slug rather than taken from the repo.
+//
+//   main: kit: target: go: module: package: 'acmesdk'
+//
+// The default concatenates `<origin><slug>sdk`, which DOUBLES the org prefix
+// whenever the slug already carries it: slug `voxgig-solardemo` under origin
+// `voxgig-sdk` produced `package voxgigvoxgigsolardemosdk`. A slug repeating
+// its org is the natural shape for a repo named `<org>-<product>`, so the
+// default now drops a leading origin prefix instead of restating it.
+//
+// This was the last of the four things the slug derives that had no override,
+// and the only one that came out wrong — see the identity note at the top of
+// model/sdkgen.aontu.
+function goPackageIdent(model: any, target: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.module?.package
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+
+  const ident = (s: string) => String(s || '').replace(/[^a-z0-9]/gi, '').toLowerCase()
+
+  const org = ident((model.origin || 'voxgig-sdk').replace(/-sdk$/, ''))
+  let slug = ident(model.name)
+
+  if ('' !== org && slug.startsWith(org)) {
+    slug = slug.slice(org.length)
+  }
+
+  return org + slug + 'sdk'
+}
+
+
 // Publication state of a target's package registry, tri-state + tag-only:
 //   'tag'      — no registry (the go family); resolved from the git tag.
 //   'pending'  — registry declared but the package is not uploaded yet
@@ -130,6 +247,25 @@ function packageName(model: any, eco: string): string {
   const origin = model.origin || 'voxgig-sdk'
   const base = origin.endsWith('-sdk') ? slug : `${slug}-sdk`
   const npmScoped = `@${origin}/${slug}${origin.endsWith('-sdk') ? '' : '-sdk'}`
+
+  // A target may name its published package outright — the escape hatch for a
+  // project whose registry name is not what the slug derives, and which cannot
+  // rename the slug without renaming its SDK classes:
+  //
+  //   main: kit: target: ts: publish: registry: package: '@acme/legacy-client'
+  //
+  // The key already existed in the schema ("registry package name ('' ->
+  // derived)") and was simply never read. Keyed by TARGET, so the ecosystem
+  // aliases ('npm', 'pypi', ...) resolve to the target that publishes to them.
+  const ECO_TARGET: Record<string, string> = {
+    npm: 'ts', pypi: 'py', gem: 'rb', luarocks: 'lua', composer: 'php',
+  }
+  const declared = model?.main?.[KIT]?.target?.[ECO_TARGET[eco] || eco]
+    ?.publish?.registry?.package
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+
   switch (eco) {
     case 'npm':
     case 'ts':
@@ -147,11 +283,11 @@ function packageName(model: any, eco: string): string {
     case 'php':
       return `${origin}/${base}`
     case 'go':
-      return `github.com/${origin}/${slug}-sdk/go`
+      return goModule(model, 'go')
     case 'go-cli':
-      return `github.com/${origin}/${slug}-sdk/go-cli`
+      return goModule(model, 'go-cli')
     case 'go-mcp':
-      return `github.com/${origin}/${slug}-sdk/go-mcp`
+      return goModule(model, 'go-mcp')
     // The notebook/analyst package layered on `py`. Distinct PyPI name so it
     // can version and publish independently of the SDK it wraps.
     case 'py-data':
@@ -214,11 +350,69 @@ function keywords(model: any): string[] {
   return ['voxgig', 'sdk', 'generated-sdk', 'openapi', 'api-client', model.name]
 }
 
-// A VALID uppercase env-var base derived from the slug: 'unsolicited-advice' ->
-// 'UNSOLICITED_ADVICE'. Use for <NAME>_APIKEY / <NAME>_TEST_LIVE so examples are
-// valid identifiers (model.NAME left a hyphen in, breaking process.env.X).
+
+// WHO WROTE THE PACKAGE — `main: kit: author` / `main: kit: contributor`.
+//
+// Attribution cannot be derived: it is not a function of the slug, the repo or
+// the API. And because generated output is OVERWRITTEN, a name hand-edited
+// into a manifest is deleted by the next regeneration — silently, because no
+// build step can tell that a person is missing. The seneca-provider target
+// dropped a hand-written provider's author and both its named contributors
+// exactly that way. So attribution is declared in the model and read here.
+//
+// An unset author is the PUBLISHER, which is what every generated SDK manifest
+// has always carried (Package_ts hardcoded it); a project that has never
+// thought about authorship keeps the previous behaviour.
+function authorInfo(model: any): { name: string, url: string } {
+  const declared = model?.main?.[KIT]?.author || {}
+
+  const name = null != declared.name && '' !== declared.name ?
+    String(declared.name) : PUBLISHER
+
+  // A declared author with no url gets none — inventing PUBLISHER_URL for a
+  // named human would credit them to Voxgig's homepage.
+  const url = null != declared.url && '' !== declared.url ? String(declared.url) :
+    (PUBLISHER === name ? PUBLISHER_URL : '')
+
+  return { name, url }
+}
+
+
+// Contributors, in sorted-key order so the manifest is byte-stable. `each`
+// rather than Object.keys: the model is an aontu map and carries metadata
+// keys alongside its entries.
+//
+// An entry with no name is DROPPED rather than rendered as `{}` — the schema
+// makes `name` required, but a partially-unified model can still reach here
+// during a dry run.
+function contributorList(model: any): { name: string, url: string }[] {
+  return each(model?.main?.[KIT]?.contributor || {})
+    .filter((c: any) => null != c && null != c.name && '' !== c.name)
+    .map((c: any) => ({
+      name: String(c.name),
+      url: null != c.url && '' !== c.url ? String(c.url) : '',
+    }))
+}
+
+// A VALID uppercase env-var token: 'unsolicited-advice' -> 'UNSOLICITED_ADVICE'.
+//
+// THE ONLY WAY to build an env-var name segment. There used to be three
+// spellings of this in the components — `envToken(name)`,
+// `nom(x, 'NAME')` (the camel form uppercased, which SWALLOWS the hyphen) and
+// `x.name.toUpperCase().replace(...)` — and they agree only while the name has
+// no hyphen in it. A slug like `voxgig-solardemo` produced both
+// `VOXGIG_SOLARDEMO_TEST_LIVE` and `VOXGIGSOLARDEMO_TEST_LIVE` in the SAME
+// generated SDK: `test/utility.ts` read one, `PlanetEntity.test.ts` the other,
+// so setting either sent half the suite live and left the rest mocked — with
+// the suite reporting green either way.
+function envToken(name: any): string {
+  return String(name || '').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+}
+
+
+// The env-var base for this SDK: <NAME>_APIKEY, <NAME>_TEST_LIVE, ...
 function envName(model: any): string {
-  return String(model.name || '').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+  return envToken(model.name)
 }
 
 export {
@@ -239,5 +433,12 @@ export {
   pkgDescription,
   nonAffiliation,
   keywords,
+  authorInfo,
+  contributorList,
   envName,
+  envToken,
+  goModule,
+  goVersion,
+  goPackageIdent,
+  packageVersion,
 }

package/src/helpers/stdrep.ts

@@ -0,0 +1,56 @@
+// Replacement keys the GENERATOR owns, merged into the project's `ctx$.stdrep`.
+//
+// `stdrep` itself is built by the consumer's `Root.ts`
+// (`names(ctx$.stdrep, model.Name, 'ProjectName')`), which lives outside this
+// package and is frozen at project-init time — so a new placeholder cannot be
+// added there without every existing project resyncing its root wiring. These
+// are added here instead, immediately before the templates that use them are
+// copied, so an old project gets them without touching its scaffold.
+
+import { envName, packageVersion } from './packageMeta'
+
+
+// PROJECTENV — the env-var base for this SDK's `<BASE>_TEST_LIVE`,
+// `<BASE>_APIKEY` and friends.
+//
+// NOT `PROJECTNAME`. That one is the camel-cased class name uppercased, which
+// SWALLOWS a hyphen: `voxgig-solardemo` becomes `VOXGIGSOLARDEMO`, while every
+// component-generated env var reads `VOXGIG_SOLARDEMO`. Both spellings used to
+// reach the same generated SDK — `test/utility.ts` (a template) read one and
+// `PlanetEntity.test.ts` (a component) the other — so setting either variable
+// sent half the suite live and left the rest mocked, green either way.
+function ensureStdrep(ctx$: any): any {
+  const stdrep = ctx$.stdrep = (ctx$.stdrep || {})
+
+  if (null == stdrep.PROJECTENV) {
+    stdrep.PROJECTENV = envName(ctx$.model)
+  }
+
+  return stdrep
+}
+
+
+// The substitutions `target add` applies when it copies a target's TEMPLATE
+// tree (tm/<t>).
+//
+// ONE definition, because two consumers must agree exactly: `target add`
+// writes the files, and `doctor` re-applies these to the scaffold before
+// comparing, to tell a substitution artefact from a real hand-edit. When
+// PROJECTVERSION was added to the writer alone, every project's VERSION file
+// immediately read as an edited master.
+function templateReplacements(model: any, tname: string): Record<string, string> {
+  return {
+    ProjectName: model?.const?.Name,
+
+    // The port's release version, read by its Makefile to build the
+    // `<target>/v<version>` tag. It comes from the same model field the
+    // generated manifest uses, so the tag and the package cannot disagree.
+    PROJECTVERSION: packageVersion(model, tname),
+  }
+}
+
+
+export {
+  ensureStdrep,
+  templateReplacements,
+}

package/src/helpers/testPolicy.ts

@@ -0,0 +1,52 @@
+// How strict the generated LIVE tests are.
+//
+// WHY THIS IS A MODEL DECISION
+//
+// The generated direct tests are deliberately lenient in live mode:
+//
+//   if (setup.live) {
+//     // Live mode is lenient: synthetic IDs frequently 4xx.
+//     if (!result.ok || result.status < 200 || result.status >= 300) {
+//       return                       // <-- passes
+//     }
+//   } else {
+//     assert(result.ok === true)
+//     ...
+//   }
+//
+// That is CORRECT for sdkgen's default case — a fleet SDK generated against
+// an arbitrary third-party public API, where synthetic IDs 4xx constantly and
+// list response shapes vary wildly. Asserting there would mean permanent red.
+//
+// It is WRONG for a project that owns the server it tests against, and those
+// projects had no way to say so. Measured on voxgig-solardemo-sdk: the live
+// TypeScript suite reports 186 pass / 0 fail against the local test app —
+// and 184 pass / 2 fail with the server STOPPED. Only the two entity `basic`
+// flows noticed. A green live run said almost nothing.
+//
+// Gaps that announce themselves as a passing test suite are worse than the
+// ones that break a build.
+
+import { KIT } from '../types'
+
+
+// True when live assertions should match the offline ones. Per-target
+// override first, then the SDK-wide default, then false.
+//
+//   main: kit: test: live: strict: true
+//   main: kit: target: go: test: live: strict: true
+function liveStrict(model: any, target?: string): boolean {
+  const perTarget = null == target ? undefined :
+    model?.main?.[KIT]?.target?.[target]?.test?.live?.strict
+
+  if (null != perTarget) {
+    return true === perTarget
+  }
+
+  return true === model?.main?.[KIT]?.test?.live?.strict
+}
+
+
+export {
+  liveStrict,
+}