@voxgig/sdkgen 2.0.2 → 3.1.0

package/src/sdkgen.ts

@@ -22,6 +22,9 @@ import type {
 import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix } from './utility'
 
 import { Main } from './cmp/Main'
+import { ExternalTarget } from './cmp/ExternalTarget'
+
+import { KIT } from '@voxgig/apidef'
 import { Deploy } from './cmp/Deploy'
 import { Entity } from './cmp/Entity'
 import { Feature } from './cmp/Feature'
@@ -45,15 +48,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,
@@ -64,7 +81,14 @@ import {
   pkgDescription,
   nonAffiliation,
   keywords,
+  authorInfo,
+  contributorList,
   envName,
+  envToken,
+  goModule,
+  goVersion,
+  goPackageIdent,
+  packageVersion,
   repoInfo,
   apiName,
   langLabel,
@@ -85,6 +109,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 +150,7 @@ const { Jostraca } = JostracaModule
 const ACTION_MAP: any = {
   target: action_target,
   feature: action_feature,
+  doctor: action_doctor,
 }
 
 
@@ -190,12 +221,70 @@ 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 }))
+    // Targets that write OUTSIDE the SDK repo (`output: path`) are generated
+    // by their own pass, rooted at that path — see cmp/ExternalTarget for why
+    // a folder name cannot do this. The in-tree pass must not see them, or
+    // the consumer Root would also emit them into `<sdk-repo>/<target>/`.
+    //
+    // `folder` may be relative (a consumer's build passes '..' from `.sdk`),
+    // so resolve it ONCE: every destination is compared against it, and a
+    // comparison between a relative and an absolute path is meaningless.
+    const root = Path.resolve(folder)
+    const external = externalTargets(model, root)
+
+    // Before ANY file is written, in-tree included: a destination that turns
+    // out to be wrong must abort the whole generation, not leave half of it
+    // done. See checkExternalFolders.
+    checkExternalFolders(external, root, fs)
+
+    const jres = await jostraca.generate(
+      jopts, () => Root({ model: 0 === external.length ? model : withoutTargets(model, external) }))
 
     showChanges(jopts.log, 'generate-result', jres, Path.dirname(process.cwd()))
 
+    for (const ext of external) {
+      // `active: false` is the project's only lever to stop the generator
+      // writing into a repo it does not own, so it has to be honoured HERE —
+      // the consumer Root iterates targets raw and does not check it. The
+      // target is still removed from the in-tree model above (withoutTargets
+      // takes every `output: path` target, active or not), so switching one
+      // off generates it nowhere rather than relocating it into
+      // `<sdk-repo>/<target>/`.
+      if (!ext.active) {
+        log.info({
+          point: 'generate-external-skip', target: ext.name, folder: ext.folder,
+          note: ext.name + ' inactive, not generated'
+        })
+        continue
+      }
+
+      log.info({
+        point: 'generate-external', target: ext.name, folder: ext.folder,
+        note: ext.name + ' -> ' + ext.folder
+      })
+
+      const eres = await jostraca.generate(
+        { ...jopts, folder: ext.folder },
+        () => ExternalTarget({
+          model, target: ext.target, cmpfolder: folder,
+          // How to walk BACK to the SDK project from the destination. A
+          // target generating out of tree usually sits beside the SDK in a
+          // known layout, and its own docs, scripts and live tests need to
+          // name that path.
+          sdkrelpath: externalSdkRel(ext, root, log),
+        }))
+
+      showChanges(jopts.log, 'generate-result', eres, Path.dirname(process.cwd()))
+    }
+
     const dlogs = dlog.log()
     if (0 < dlogs.length) {
       for (let dlogentry of dlogs) {
@@ -209,7 +298,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 +310,7 @@ function SdkGen(opts: SdkGenOptions) {
 
     const ctx = resolveActionContext()
 
-    await actionFunc(pargs, ctx)
+    return await actionFunc(pargs, ctx)
   }
 
 
@@ -297,12 +386,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,
   }
@@ -338,6 +434,226 @@ SdkGen.makeBuild = async function(opts: SdkGenOptions) {
 
 
 
+type ExternalSpec = {
+  name: string
+  target: any
+  folder: string
+  active: boolean
+}
+
+
+// Targets declaring `output: path` — generated into their own repo rather
+// than into `<sdk-repo>/<target>/`.
+//
+// A relative path resolves against the SDK repo root, so a sibling checkout
+// is '../<repo>'. That is deliberately the SAME base the generator writes
+// everything else against: a path in the model should not depend on the
+// directory the command happened to be run from.
+//
+// An INACTIVE target is still listed: it must be taken out of the in-tree
+// model (see withoutTargets) so that switching it off does not silently
+// relocate it into `<sdk-repo>/<target>/`. The generate loop skips it.
+function externalTargets(model: any, folder: string): ExternalSpec[] {
+  const targets = model?.main?.[KIT]?.target || {}
+
+  return Object.keys(targets).sort()
+    .map((name: string) => ({ name, target: targets[name] }))
+    .filter((t: any) => {
+      const path = t.target?.output?.path
+      return null != path && '' !== path
+    })
+    .map((t: any) => ({
+      ...t,
+      folder: Path.resolve(folder, String(t.target.output.path)),
+      active: false !== t.target.active,
+    }))
+}
+
+
+// The `.jostraca` bookkeeping tree (meta log + a duplicate of the last
+// generated output) that jostraca leaves at an output root. It is the only
+// on-disk evidence that this toolchain has generated into a directory
+// before, so it doubles as the OWNERSHIP MARKER: a destination carrying one
+// has been generated into already, whoever set it up.
+const EXTERNAL_MARKER = '.jostraca'
+
+// Entries that do not count as content when deciding whether a destination
+// is empty. A `git init` (or a clone of an empty repo) leaves only `.git`,
+// and that is exactly the destination a FIRST generation is aimed at.
+const EXTERNAL_EMPTY = ['.git', '.DS_Store']
+
+
+// Refuse a destination the project cannot have meant.
+//
+// The external pass is the one code path that writes outside the repo it was
+// pointed at, at a filesystem path taken verbatim from the model — and
+// generation is overwrite, not merge, while jostraca's ensureDir creates
+// missing parents. So a mistyped `output: path` does not fail: it fabricates
+// a package tree at an arbitrary location, or overwrites an unrelated repo's
+// package.json, README.md, LICENSE and CI workflow in place. The only trace
+// was one INFO line naming the resolved folder.
+//
+// A destination must therefore be:
+//   - outside the SDK project, in BOTH directions — inside it is what a
+//     typo like '.' or 'ts' produces (and the external pass runs SECOND, so
+//     it wins over what the in-tree pass just wrote), while a destination
+//     that CONTAINS the project is what '..' produces;
+//   - claimed by no other target;
+//   - and either absent, empty, or carrying the marker a previous
+//     generation left there.
+//
+// Anything else is refused with both paths named. NOT skipped: a project
+// generating somewhere other than it believes must be told. A destination
+// that legitimately holds other content first (a repo seeded with a README
+// and LICENCE) says so once in the model, with `output: adopt: true`.
+function checkExternalFolders(external: ExternalSpec[], root: string, fs: any) {
+  const claimed: Record<string, string> = {}
+
+  for (const ext of external) {
+    // An inactive target writes nothing, so its destination is not a hazard —
+    // and switching a target off must not require keeping its now-unused
+    // path valid.
+    if (!ext.active) continue
+
+    const where = 'Target "' + ext.name + '" has output path "' +
+      ext.target.output.path + '", which resolves to: ' + ext.folder +
+      '\n  (SDK project: ' + root + ')'
+
+    if (ext.folder === root || folderContains(root, ext.folder)) {
+      throw new SdkGenError(
+        'External target output path is inside the SDK project.\n  ' + where +
+        '\n  A target generating into the SDK project must leave `output: ' +
+        'path` unset — it is then generated in-tree, as <sdk-project>/' +
+        ext.name + '/.')
+    }
+
+    if (folderContains(ext.folder, root)) {
+      throw new SdkGenError(
+        'External target output path contains the SDK project.\n  ' + where +
+        '\n  Generation would write this package over the directory holding ' +
+        'the SDK project itself.')
+    }
+
+    if (null != claimed[ext.folder]) {
+      throw new SdkGenError(
+        'External target output path is already claimed by target "' +
+        claimed[ext.folder] + '".\n  ' + where +
+        '\n  Two targets generating into the same folder overwrite each ' +
+        'other, in target-name order.')
+    }
+    claimed[ext.folder] = ext.name
+
+    if (!fs.existsSync(ext.folder)) continue
+
+    if (!fs.statSync(ext.folder).isDirectory()) {
+      throw new SdkGenError(
+        'External target output path is not a folder.\n  ' + where)
+    }
+
+    if (true === ext.target.output.adopt) continue
+
+    const entries: string[] = fs.readdirSync(ext.folder)
+      .map((entry: any) => String(entry))
+
+    if (entries.includes(EXTERNAL_MARKER)) continue
+
+    const content = entries.filter((entry) => !EXTERNAL_EMPTY.includes(entry))
+
+    if (0 < content.length) {
+      throw new SdkGenError(
+        'External target output folder already holds content this generator ' +
+        'did not write.\n  ' + where +
+        '\n  Found: ' + content.slice(0, 8).join(', ') +
+        (8 < content.length ? ', ...' : '') +
+        '\n  Generation OVERWRITES, so this would replace that content. ' +
+        'Check the path;\n  if the folder is right, declare it: `main: kit: ' +
+        'target: \'' + ext.name + '\': output: adopt: true`.')
+    }
+  }
+}
+
+
+// Is `path` inside `folder`? Both must already be resolved. Path.relative
+// rather than a string prefix, so that a sibling whose name merely STARTS
+// with the folder's ('/x/sdk' vs '/x/sdk-provider') is not read as nested.
+function folderContains(folder: string, path: string): boolean {
+  const rel = Path.relative(folder, path)
+  return '' !== rel && !rel.startsWith('..' + Path.sep) && '..' !== rel &&
+    !Path.isAbsolute(rel)
+}
+
+
+// The path from the destination back to the SDK project, which the target's
+// own docs, scripts and live tests name (the companion test server lives in
+// the SDK repo and is not published).
+//
+// It is DERIVED from the two resolved folders by default, which is only
+// honest while the walk back crosses nothing the model does not name. It
+// does not for `output: path: '../<repo>'`; it does for anything ascending
+// further. voxgig-solardemo-sdk declares '../../seneca/solardemo-provider'
+// and the derived inverse came out as '../../voxgig-sdk/voxgig-solardemo-sdk'
+// — where `voxgig-sdk` is the name of the WORKSPACE DIRECTORY holding the SDK
+// checkout on one machine, no part of the model. That string is committed
+// into the destination's README.md and three test files, so a second
+// developer with the same two repos under a differently named parent
+// regenerates a spurious diff in tracked files and an instruction path that
+// is wrong on the first machine.
+//
+// So a project that ascends further declares the walk back explicitly, as
+// `output: sdkrel`, and is warned until it does.
+function externalSdkRel(ext: ExternalSpec, root: string, log: any): string {
+  const declared = String(ext.target.output?.sdkrel || '')
+  if ('' !== declared) return declared
+
+  const derived = Path.relative(ext.folder, root).split(Path.sep).join('/')
+
+  // Every segment that is not '..' is a real directory name on the way back
+  // down to the SDK project. The LAST is the project's own folder; any
+  // earlier one is a directory ABOVE it, which nothing in the model declares.
+  const named = derived.split('/').filter((seg) => '..' !== seg)
+
+  if (1 < named.length) {
+    log.warn({
+      point: 'external-sdkrel-derived', target: ext.name, sdkrel: derived,
+      note: ext.name + ': path back to the SDK project derived as \'' +
+        derived + '\', which names ' + (named.length - 1) +
+        ' directory(s) above the SDK project that the model does not ' +
+        'declare — this machine\'s layout will be committed to the ' +
+        'generated files. Declare `output: sdkrel` instead.'
+    })
+  }
+
+  return derived
+}
+
+
+// The model the IN-TREE pass sees: the same model with the out-of-tree
+// targets taken out.
+//
+// A shallow clone down to `target` only — the model is large, entities and
+// features are shared with the external pass, and a deep copy would both
+// cost and quietly break identity comparisons.
+function withoutTargets(model: any, external: { name: string }[]): any {
+  const drop = new Set(external.map((e) => e.name))
+  const targets = model?.main?.[KIT]?.target || {}
+
+  const kept: any = {}
+  for (const name of Object.keys(targets)) {
+    if (!drop.has(name)) {
+      kept[name] = targets[name]
+    }
+  }
+
+  return {
+    ...model,
+    main: {
+      ...model.main,
+      [KIT]: { ...model.main[KIT], target: kept },
+    },
+  }
+}
+
+
 // Adapted from https://github.com/sindresorhus/import-fresh - Thanks!
 function clear(path: string) {
   if (null == path) {
@@ -375,7 +691,11 @@ function clear(path: string) {
 
 export type {
   SdkGenOptions,
+  ExampleLang,
   DepEntry,
+  FeatureSource,
+  DoctorReport,
+  RegisterOptions,
 }
 
 export type {
@@ -448,6 +768,7 @@ export {
   ReadmeExplanation,
   ReadmeRef,
   FeatureHook,
+  registerComponent,
 
   Jostraca,
   SdkGen,
@@ -470,6 +791,9 @@ export {
   OP_SUFFIX,
   opTypeName,
   opParams,
+  opActions,
+  entityActions,
+  entityPath,
   opRequestShape,
   entityIdField,
   entityDataIdField,
@@ -484,12 +808,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,
@@ -503,7 +841,14 @@ export {
   pkgDescription,
   nonAffiliation,
   keywords,
+  authorInfo,
+  contributorList,
   envName,
+  envToken,
+  goModule,
+  goVersion,
+  goPackageIdent,
+  packageVersion,
   repoInfo,
   apiName,
   langLabel,

package/src/types.ts

@@ -56,8 +56,31 @@ type ModelTarget = NameCases & {
   active?: boolean
   title?: string
   base?: string
-  module?: { name?: string }
+  module?: { name?: string, path?: string, package?: string, goversion?: string }
   srcfeature?: boolean
+
+  // Where this target's files land. Present means OUT OF TREE: the target
+  // gets its own generate() pass rooted at `path` rather than a folder inside
+  // the SDK repo — see cmp/ExternalTarget and
+  // docs/explanation/out-of-tree-targets.
+  //
+  // Typed rather than left to the index signature because `externalTargets()`
+  // decides from these keys whether to write OUTSIDE the repo, and a
+  // destination path read off a bare `any` is one a rename can silently
+  // change to undefined.
+  output?: {
+    path?: string
+    repo?: string
+    adopt?: boolean
+    sdkrel?: string
+  }
+
+  // Per-generation-phase activation. A consumer target (go-cli, go-mcp,
+  // py-data, seneca-provider) switches every phase off and emits its whole
+  // package from Main. Absent — or present with no `active` — means the phase
+  // runs: the defaults are inclusive.
+  phase?: Record<string, { active?: boolean }>
+
   [extra: string]: any
 }
 

package/src/utility.ts

@@ -6,8 +6,17 @@ import { JostracaResult } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
 
 
+// Where a per-target component is loaded from: `<project>/.sdk/dist/<path>`.
+//
+// `ctx$.folder` is jostraca's OUTPUT folder, which is the project for an
+// ordinary target but the destination repo for one generating out of tree
+// (`output: path`). Components always live in the project that owns the
+// model, never in the place its files land, so an external pass sets
+// `ctx$.cmpfolder` and this prefers it. Without that, generating out of tree
+// looks for `<destination>/.sdk/dist/cmp/...` and fails to resolve.
 function resolvePath(ctx$: any, path: string): any {
-  const fullpath = Path.join(ctx$.folder, '.sdk', 'dist', path)
+  const base = null == ctx$.cmpfolder ? ctx$.folder : ctx$.cmpfolder
+  const fullpath = Path.join(base, '.sdk', 'dist', path)
   return fullpath
 }
 

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;