@voxgig/sdkgen 2.0.2 → 3.1.0

package/src/helpers/dryrun.ts

@@ -0,0 +1,57 @@
+// Report what a dry run WOULD have done.
+//
+// `@voxgig/util`'s showChanges only lists merged and conflicted files, which
+// on a fresh `target add` is nothing at all — so `-y target add ts` printed
+// `** DRY RUN **`, listed no files, and (before the control fix) wrote them
+// anyway. A preview that shows nothing is indistinguishable from a preview of
+// nothing, which is exactly the wrong answer for the command whose whole job
+// is to overwrite a project's vendored scaffold.
+
+// Subset of jostraca's result: the per-outcome file lists.
+type FileLists = {
+  written?: string[]
+  merged?: string[]
+  conflicted?: string[]
+  unchanged?: string[]
+  preserved?: string[]
+}
+
+
+// Log every path the run touched, one line each, plus a total. `written`
+// covers both new and overwritten files — in a dry run nothing reached disk,
+// so the list IS the preview.
+function showDryrun(log: any, point: string, jres: any, folder?: string) {
+  const files: FileLists = (jres && jres.files) || {}
+
+  const prefix = null == folder ? '' :
+    (folder.endsWith('/') ? folder : folder + '/')
+
+  const rel = (p: string) => ('' !== prefix && p.startsWith(prefix)) ?
+    p.slice(prefix.length) : p
+
+  let count = 0
+
+  for (const kind of ['written', 'merged', 'conflicted'] as const) {
+    for (const file of (files[kind] || [])) {
+      count++
+      log.info({ point, file, kind, note: kind + ': ' + rel(file) })
+    }
+  }
+
+  log.info({
+    point, count,
+    note: '** DRY RUN ** ' + count + ' file' + (1 === count ? '' : 's') +
+      ' would change; nothing was written'
+  })
+
+  return count
+}
+
+
+export type {
+  FileLists,
+}
+
+export {
+  showDryrun,
+}

package/src/helpers/featureSource.ts

@@ -0,0 +1,208 @@
+// Locate the per-feature source inside a target's template tree.
+//
+// WHY THIS EXISTS
+//
+// `target add` is supposed to copy source for the features the model
+// declares, and nothing else. It used to do that with a single hardcoded
+// path assumption:
+//
+//   Copy({ from: 'tm/<lang>', exclude: [/src\/feature/] })
+//   Folder({ name: 'src/feature' }, () => /* copy each model feature */)
+//
+// That assumption holds for exactly two targets. `ts` and `js` keep feature
+// source at `src/feature/<name>/`; everyone else does something else —
+// `tm/go/feature/retry_feature.go`, `tm/rust/feature/retry.rs`,
+// `tm/py/pkg/feature/retry_feature.py`, `tm/dart/lib/feature/retry/...`,
+// `tm/swift/Sources/ProjectNameSDK/feature/RetryFeature.swift`, and so on.
+// None of those match `src/feature`, so the exclude never saw them and every
+// shipped feature was copied into every project regardless of the model: 272
+// stray source files across 17 targets for a project declaring no features
+// at all. (For those targets `src/feature/<name>/` holds only a `.gitkeep`
+// placeholder — the old gate was gating empty directories.)
+//
+// So instead of encoding one layout, DISCOVER it: walk the template tree,
+// treat any directory named `feature` as a feature container, and map each
+// entry inside it back to a feature name. That covers every layout above,
+// and a target added later gets gated without anyone editing this file.
+//
+// The mapping is deliberately conservative. An entry only counts as feature
+// source when its derived name is one the generator can actually supply
+// (`availableFeatures`, read from `model/feature/*.aontu`). Everything else
+// inside a feature directory — `feature_options.go`, `FeatureOptions.cs`,
+// `mod.rs`, `support.rs`, `options.hpp`, `__init__.py`, `README.md`, and the
+// `harness.ts` under `test/feature/` — derives a name no feature has, so it
+// is left alone.
+
+import Path from 'node:path'
+
+import { KIT, getModelPath } from '@voxgig/apidef'
+
+
+// One feature's source within a target template tree.
+type FeatureSource = {
+  // Feature name, lowercased ('retry').
+  name: string
+
+  // Path relative to the target template root ('feature/retry_feature.go',
+  // 'lib/feature/retry'), always with forward slashes.
+  path: string
+
+  // True when `path` is a directory holding the whole feature.
+  folder: boolean
+}
+
+
+// Directory name that marks a feature container. Kept exact (not a substring
+// match) so `utility/feature_add.go` and `test/feature_test.go` — which are
+// shared machinery, not per-feature source — are never treated as features.
+const FEATURE_DIR = 'feature'
+
+
+// Derive the feature name an entry inside a feature directory belongs to.
+// Returns the lowercased name, which the caller then checks against the
+// available set.
+//
+//   retry_feature.go   -> retry     (go, py, rb, lua, perl)
+//   RetryFeature.cs    -> retry     (csharp, java, kotlin, scala, swift, php)
+//   retry.rs           -> retry     (rust, c, cpp, zig, elixir)
+//   retry/             -> retry     (ts, js, dart)
+//   feature_options.go -> feature_options   (not a feature; `_feature` is a
+//                                            prefix here, not a suffix)
+//   FeatureOptions.cs  -> featureoptions    (ditto)
+function featureOf(entry: string, folder: boolean): string {
+  if (folder) {
+    return entry.toLowerCase()
+  }
+
+  // Only the final extension goes; `feature.test.ts` style names keep the
+  // rest so they cannot collide with a bare feature name.
+  const stem = entry.replace(/\.[^.]+$/, '')
+
+  return stem
+    .replace(/_feature$/i, '')
+    .replace(/Feature$/, '')
+    .toLowerCase()
+}
+
+
+// Feature names this generator can supply, read from the scaffold's
+// `model/feature/*.aontu`. This is the authoritative catalogue: a name not in
+// it is not a feature, so nothing outside it is ever excluded.
+function availableFeatures(fs: any, sdkfolder: string): string[] {
+  const dir = Path.join(sdkfolder, 'model', 'feature')
+
+  if (!fs.existsSync(dir)) {
+    return []
+  }
+
+  return fs.readdirSync(dir)
+    .filter((n: string) => n.endsWith('.aontu') && 'feature-index.aontu' !== n)
+    .map((n: string) => n.replace(/\.aontu$/, '').toLowerCase())
+    .sort()
+}
+
+
+// Walk a target's template tree and return every per-feature source entry.
+// `tmfolder` is the target template root (`<sdk>/tm/<lang>`).
+function findFeatureSources(fs: any, tmfolder: string, available: string[]): FeatureSource[] {
+  const known = new Set(available)
+  const found: FeatureSource[] = []
+
+  if (!fs.existsSync(tmfolder)) {
+    return found
+  }
+
+  // `rel` is relative to tmfolder, '' at the root.
+  const walk = (rel: string) => {
+    const abs = '' === rel ? tmfolder : Path.join(tmfolder, rel)
+    const entries = fs.readdirSync(abs).sort()
+
+    for (const entry of entries) {
+      const entryrel = '' === rel ? entry : rel + '/' + entry
+      const folder = fs.statSync(Path.join(tmfolder, entryrel)).isDirectory()
+
+      // Inside a feature container every entry is a candidate, and a
+      // candidate directory is the whole feature — do not descend into it
+      // looking for more.
+      if (FEATURE_DIR === Path.basename(rel)) {
+        const name = featureOf(entry, folder)
+        if (known.has(name)) {
+          found.push({ name, path: entryrel, folder })
+          continue
+        }
+      }
+
+      if (folder) {
+        walk(entryrel)
+      }
+    }
+  }
+
+  walk('')
+
+  return found
+}
+
+
+// Turn discovered sources into path patterns for a jostraca `Copy` exclude.
+//
+// jostraca tests each candidate against the path built up during its walk,
+// which carries the enclosing node path as a prefix — so anchor on a
+// segment boundary at both ends rather than on the whole string. A folder
+// source matches everything beneath it; a file source matches only itself.
+function featureExcludes(sources: FeatureSource[]): RegExp[] {
+  return sources.map((s) => new RegExp(
+    '(^|/)' + s.path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + (s.folder ? '/' : '$')
+  ))
+}
+
+
+// Path patterns for templates that only compile with the COMPLETE feature
+// set — see `feature.fullset` in each target's model. These are the
+// cross-feature test suites: one file per target that constructs every
+// shipped feature type by name (`feature.NewRetryFeature`,
+// `RUSTCRATE::feature::retry::RetryFeature`, ...). Trimming the feature set
+// without dropping them leaves a project that will not compile.
+function fullsetExcludes(paths: string[]): RegExp[] {
+  return (paths || []).map((p) => new RegExp(
+    '(^|/)' + String(p).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$'
+  ))
+}
+
+
+// Generate-time guard for the `src/feature/<name>/` layout (ts, js).
+//
+// Root renders one Feature component per ACTIVE feature, but Main then
+// copies the whole `tm/<lang>` tree — which puts a deactivated feature's
+// source straight back, silently undoing the filter. `target add` keeps
+// deactivated features out of `tm` in the first place; this covers the case
+// where a feature is switched off AFTER it was added.
+//
+// Only declared-but-inactive features are excluded. `base` and anything else
+// the model never mentions is left alone.
+function srcFeatureExcludes(model: any): RegExp[] {
+  const all = getModelPath(model, `main.${KIT}.feature`,
+    { required: false, only_active: false }) || {}
+  const active = getModelPath(model, `main.${KIT}.feature`,
+    { required: false }) || {}
+
+  return Object.keys(all)
+    .filter((name: string) => null == active[name])
+    .map((name: string) => new RegExp(
+      '(^|/)src/feature/' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/'
+    ))
+}
+
+
+export type {
+  FeatureSource,
+}
+
+export {
+  featureOf,
+  availableFeatures,
+  findFeatureSources,
+  featureExcludes,
+  fullsetExcludes,
+  srcFeatureExcludes,
+}

package/src/helpers/naming.ts

@@ -209,16 +209,85 @@ function safeVarName(name: string, lang: string): string {
 }
 
 
+// Members the generated PHP SDK class already declares (see the php target's
+// fragment/Main.fragment.php). An entity accessor or backing field reusing one
+// is a FATAL redeclare — PHP will not parse the file, so the SDK yields zero
+// working tests rather than a degraded one.
+//
+// PHP method names are CASE-INSENSITIVE at declaration time, hence the
+// lowercased comparison: an entity `graph_ql` derives the accessor `GraphQl()`,
+// the same declaration as the SDK's own `graphql()`.
+//
+// This lives here, not in the php component, because the ACCESSOR NAME has to
+// agree across the SDK class and every doc/example component that calls it.
+// It did not: MainEntity_php emitted `Test_()` for an entity named `test`
+// while eight readme components emitted `Test()`, so the generated examples
+// called the static test-mode constructor and died with
+// "Call to undefined method <Name>SDK::load()".
+const PHP_SDK_METHODS = new Set([
+  'construct', '__construct', 'direct', 'get_root_ctx', 'get_utility',
+  'graphql', 'op_allowed', 'op_denied', 'options_map', 'prepare',
+  'raw_request', 'test',
+])
+
+// Backing fields the generated SDK object already holds, in EVERY target that
+// caches its entity accessors in `_<name>`. php spells it `$this->_utility`
+// and lua `self._utility`, but it is one hazard: the accessor's cache slot
+// silently aliases the SDK's own field, so `client:Utility()` hands back the
+// internal utility object and every entity method on it is nil.
+const SDK_FIELDS = new Set(['rootctx', 'utility', 'client', 'entctx'])
+
+
+/** The PHP accessor method for an entity: `$client-><Name>()`. */
+function phpEntityAccessor(Name: string): string {
+  return PHP_SDK_METHODS.has(String(Name).toLowerCase()) ? Name + '_' : Name
+}
+
+
+/**
+ * The backing field for an entity accessor's cache slot (`$this->_<name>`,
+ * `self._<name>`). Target-neutral: the colliding names are the SDK's own
+ * fields, which the targets share.
+ */
+function entityCacheField(name: string): string {
+  return SDK_FIELDS.has(String(name).toLowerCase()) ? name + '_' : name
+}
+
+
+// Symbols a doc example CALLS, which a same-named example variable would
+// shadow. The variable is syntactically fine; the example then fails at
+// RUNTIME, which is far harder to read than a compile error:
+//
+//   const consoles = await client.Console().list()
+//   for (const console of consoles) { console.log(console) }
+//   -> "console.log is not a function"   (nexarda, an API with a Console entity)
+//
+// Only languages where a plain variable can capture the symbol are listed.
+// php is absent on purpose: its variables carry a `$` sigil, so `$echo` can
+// never shadow `echo`.
+const EXAMPLE_GLOBALS: Record<string, string[]> = {
+  ts: ['console', 'process', 'globalThis'],
+  js: ['console', 'process', 'globalThis'],
+  py: ['print'],
+  rb: ['puts'],
+  lua: ['print'],
+  go: ['fmt'],
+}
+
+
 // A variable name for a doc EXAMPLE entity. Doc examples bind the SDK instance
 // to `client` (e.g. `const client = ...SDK.test()`), so an entity whose
 // lowercased name is also `client` — an API with a `Client` entity — would
 // shadow it: `const client = client.Client()...` is self-referential (TS2448/
 // TS7022) and breaks the readme_examples type-check. Append `_` to keep the
-// example variable distinct from the SDK instance. Also applies the normal
+// example variable distinct from the SDK instance. The same applies to any
+// symbol the example itself calls (EXAMPLE_GLOBALS). Also applies the normal
 // language-reserved-word guard.
 function exampleVarName(name: string, lang: string): string {
   const v = safeVarName(name, lang)
-  return 'client' === v ? v + '_' : v
+  if ('client' === v) return v + '_'
+  if ((EXAMPLE_GLOBALS[lang] || []).includes(v)) return v + '_'
+  return v
 }
 
 
@@ -256,6 +325,8 @@ export {
   isReservedName,
   safeVarName,
   exampleVarName,
+  phpEntityAccessor,
+  entityCacheField,
   isRbCoreConstant,
   rbSafeTypeName,
   isSwiftSdkType,

package/src/helpers/opExample.ts

@@ -20,6 +20,8 @@ import { each } from 'jostraca'
 import { canonKey } from './canonType'
 import { opRequestShape, entityIdField } from './opShape'
 
+import { phpEntityAccessor } from './naming'
+
 
 type ExampleLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go'
 
@@ -35,7 +37,19 @@ function litFor(lang: ExampleLang, type: any): string {
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'py' === lang ? 'True' : ('rb' === lang ? 'true' : 'true')
   if ('ARRAY' === k) return ('lua' === lang) ? '{}' : ('go' === lang ? '[]any{}' : '[]')
-  if ('OBJECT' === k) return ('go' === lang) ? 'map[string]any{}' : '{}'
+  // PHP has no `{}` literal — `["data" => {}]` is a parse error, which took
+  // the whole generated README down for any entity with an object-typed
+  // writable field (dymo-api-introduction, html-creator). Arrays serve as both
+  // list and map, so `[]` is the empty object too. Ruby and Lua likewise want
+  // their own empty-hash/table spelling rather than JS's.
+  if ('OBJECT' === k) {
+    if ('go' === lang) return 'map[string]any{}'
+    if ('php' === lang) return '[]'
+    if ('rb' === lang) return '{}'
+    if ('lua' === lang) return '{}'
+    if ('py' === lang) return '{}'
+    return '{}'
+  }
   return '"example"'
 }
 
@@ -154,7 +168,10 @@ function primaryOpCall(
   if ('go' === lang) { factory = `client.${eName}(nil)`; sep = '.' }
   else if ('lua' === lang) { factory = `client:${eName}()`; sep = ':' }
   else if ('rb' === lang) { factory = `client.${eName}`; sep = '.' }
-  else if ('php' === lang) { factory = `$client->${eName}()`; sep = '->' }
+  // php mangles an accessor that would collide with an SDK class member
+  // (see phpEntityAccessor); the example has to call the name that is
+  // actually declared, or it invokes the SDK's own method instead.
+  else if ('php' === lang) { factory = `$client->${phpEntityAccessor(eName)}()`; sep = '->' }
   else { factory = `client.${eName}()`; sep = '.' }
 
   // Argument string per op + language.

package/src/helpers/opShape.ts

@@ -127,6 +127,68 @@ type OpShapeItem = {
 // list-by-parent-id call failing because sibling routes' ids are demanded —
 // and steers callers into passing keys that flip runtime point dispatch to
 // the wrong route.)
+// The action names an op multiplexes, from its points' `select.$action`.
+//
+// A custom POST route like `/api/planet/{id}/terraform` is folded into the
+// `create` op as an alternative point, discriminated at call time by
+// `$action` in the data argument. The mechanism worked and was documented
+// NOWHERE — not in the README, not in the reference — so for an API with two
+// such routes, two of its six endpoints were unreachable by anyone using the
+// documented interface. Generated docs list them via this helper.
+function opActions(op: any): { action: string, path: string }[] {
+  const points: any[] = op && op.points ? each(op.points) : []
+
+  return points
+    .filter((pt: any) => null != (pt && pt.select && pt.select['$action']))
+    .map((pt: any) => ({
+      action: String(pt.select['$action']),
+      path: String(pt.orig || ''),
+    }))
+    .sort((a, b) => a.action < b.action ? -1 : a.action > b.action ? 1 : 0)
+}
+
+
+// True when any of the entity's ops multiplexes a custom action.
+function entityActions(entity: any): { op: string, action: string, path: string }[] {
+  const out: { op: string, action: string, path: string }[] = []
+
+  each(entity && entity.op).forEach((op: any) => {
+    opActions(op).forEach((a) => out.push({ op: op.name, ...a }))
+  })
+
+  return out
+}
+
+
+// The entity's own API path — the route a reader should recognise it by.
+//
+// NOT `points[0]` across every op flattened. Ops iterate in sorted-key order,
+// so `create` came first, and an entity whose create op folds in a custom
+// action (`/api/planet/{id}/forbid`) advertised THAT as its path. The
+// canonical route is the collection or record route, and never an action.
+function entityPath(entity: any): string {
+  const ops: any = (entity && entity.op) || {}
+
+  for (const opname of ['list', 'load', 'create', 'update', 'remove']) {
+    const op = ops[opname]
+    if (null == op) {
+      continue
+    }
+
+    const points: any[] = op.points ? each(op.points) : []
+    const canonical = points.filter((pt: any) =>
+      null == (pt && pt.select && pt.select['$action']))
+
+    const pick = (0 < canonical.length ? canonical : points)[0]
+    if (null != pick && null != pick.orig && '' !== pick.orig) {
+      return String(pick.orig)
+    }
+  }
+
+  return ''
+}
+
+
 function opParams(op: any): any[] {
   let points: any[] = op && op.points ? each(op.points) : []
 
@@ -533,6 +595,9 @@ export {
   entityCollection,
   opTypeName,
   opParams,
+  opActions,
+  entityActions,
+  entityPath,
   opRequestShape,
   entityIdField,
   entityDataIdField,