@voxgig/sdkgen 2.0.1 → 3.0.0

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,
+}

package/src/sdkgen.ts

@@ -45,15 +45,29 @@ import { ReadmeHowto } from './cmp/ReadmeHowto'
 import { ReadmeExplanation } from './cmp/ReadmeExplanation'
 import { ReadmeRef } from './cmp/ReadmeRef'
 import { FeatureHook } from './cmp/FeatureHook'
+import { registerComponent } from './cmp/Registered'
+import type { RegisterOptions } from './cmp/Registered'
 
 import { buildIdNames } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, canonToDtype, canonKey } from './helpers/canonType'
-import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
-import { isReservedName, safeVarName, exampleVarName, isRbCoreConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
+import { OP_SUFFIX, opTypeName, opParams, opActions, entityActions, entityPath, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
+import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
 import { serverVariables, hasServerVariables } from './helpers/serverVars'
+import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
+import type { ExampleLang } from './helpers/opExample'
+import { liveStrict } from './helpers/testPolicy'
+import {
+  featureOf,
+  availableFeatures,
+  findFeatureSources,
+  featureExcludes,
+  fullsetExcludes,
+  srcFeatureExcludes,
+} from './helpers/featureSource'
+import type { FeatureSource } from './helpers/featureSource'
 import {
   packageName,
   installCommand,
@@ -65,6 +79,11 @@ import {
   nonAffiliation,
   keywords,
   envName,
+  envToken,
+  goModule,
+  goVersion,
+  goPackageIdent,
+  packageVersion,
   repoInfo,
   apiName,
   langLabel,
@@ -85,6 +104,12 @@ import {
   feature_add,
 } from './action/feature'
 
+import {
+  action_doctor,
+  doctor,
+} from './action/doctor'
+import type { DoctorReport } from './action/doctor'
+
 
 
 // TODO: use shape
@@ -120,6 +145,7 @@ const { Jostraca } = JostracaModule
 const ACTION_MAP: any = {
   target: action_target,
   feature: action_feature,
+  doctor: action_doctor,
 }
 
 
@@ -190,6 +216,12 @@ function SdkGen(opts: SdkGenOptions) {
       // at the scaffold source (create-sdkgen build/sdkgen.js: existing.txt =
       // { write:true, merge:false }); see docs/explanation/regeneration-overwrite.md.
       existing: opts.existing,
+      // Per-call, for the same reason the actions pass it: jostraca applies
+      // OptionsShape to `generate`'s own options first, so its
+      // `control.dryrun: false` default wins over the instance-level flag.
+      control: {
+        dryrun: !!opts.dryrun
+      },
     }
 
     const jres = await jostraca.generate(jopts, () => Root({ model }))
@@ -209,7 +241,7 @@ function SdkGen(opts: SdkGenOptions) {
   }
 
 
-  async function action(args: string[]) {
+  async function action(args: string[]): Promise<any> {
     const pargs = args.map(arg => Jsonic(arg))
 
     const actname = args[0]
@@ -221,7 +253,7 @@ function SdkGen(opts: SdkGenOptions) {
 
     const ctx = resolveActionContext()
 
-    await actionFunc(pargs, ctx)
+    return await actionFunc(pargs, ctx)
   }
 
 
@@ -297,12 +329,19 @@ function SdkGen(opts: SdkGenOptions) {
     }
   }
 
+  // Has this project's `.sdk/` drifted from the scaffold? See action/doctor.
+  const check = async (): Promise<ActionResult> => {
+    const ctx = resolveActionContext()
+    return doctor(ctx)
+  }
+
 
 
   return {
     pino: pino as any,
     generate,
     action,
+    check,
     target,
     feature,
   }
@@ -375,7 +414,11 @@ function clear(path: string) {
 
 export type {
   SdkGenOptions,
+  ExampleLang,
   DepEntry,
+  FeatureSource,
+  DoctorReport,
+  RegisterOptions,
 }
 
 export type {
@@ -448,6 +491,7 @@ export {
   ReadmeExplanation,
   ReadmeRef,
   FeatureHook,
+  registerComponent,
 
   Jostraca,
   SdkGen,
@@ -470,6 +514,9 @@ export {
   OP_SUFFIX,
   opTypeName,
   opParams,
+  opActions,
+  entityActions,
+  entityPath,
   opRequestShape,
   entityIdField,
   entityDataIdField,
@@ -484,12 +531,26 @@ export {
   isReservedName,
   safeVarName,
   exampleVarName,
+  phpEntityAccessor,
+  entityCacheField,
   isRbCoreConstant,
   rbSafeTypeName,
   isSwiftSdkType,
   swiftSafeTypeName,
   serverVariables,
   hasServerVariables,
+  liveStrict,
+  primaryOpCall,
+  idLiteral,
+  matchArg,
+  dataArg,
+  litFor,
+  featureOf,
+  availableFeatures,
+  findFeatureSources,
+  featureExcludes,
+  fullsetExcludes,
+  srcFeatureExcludes,
   jsProp,
   jsOptProp,
   jsKey,
@@ -504,6 +565,11 @@ export {
   nonAffiliation,
   keywords,
   envName,
+  envToken,
+  goModule,
+  goVersion,
+  goPackageIdent,
+  packageVersion,
   repoInfo,
   apiName,
   langLabel,

package/project/.sdk/tm/rust/feature/mod.rs

@@ -1,24 +0,0 @@
-// ProjectName SDK features (mirrors tm/go/feature). Each feature is a
-// Feature trait object registered on the client; `support` carries the
-// shared option readers (go feature_options.go).
-
-pub mod support;
-
-pub mod audit;
-pub mod base;
-pub mod cache;
-pub mod clienttrack;
-pub mod debug;
-pub mod idempotency;
-pub mod log;
-pub mod metrics;
-pub mod netsim;
-pub mod paging;
-pub mod proxy;
-pub mod ratelimit;
-pub mod rbac;
-pub mod retry;
-pub mod streaming;
-pub mod telemetry;
-pub mod test;
-pub mod timeout;