@voxgig/sdkgen 4.7.0 → 4.8.1

package/src/helpers/pointPath.ts

@@ -0,0 +1,118 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+// A point's path, as apidef resolves it.
+//
+// apidef ADR-003: the model carries the path as a typed segment vector —
+// `[{ lit: 'element' }, { var: 'id' }]` — and no brace-templated string. A
+// `var` names one of the point's `args.params` directly, so a consumer walks
+// the vector instead of parsing anything.
+//
+// The generated SDK runtimes still speak the older braced-string form
+// (`['element', '{id}']`), which this file reconstructs in ONE place. Every
+// generation-time consumer and the embedded config go through here, so when
+// the runtimes move onto segments there is a single call site to retire —
+// rather than the twenty-odd hand-written brace parsers ADR-003 is about.
+
+
+import { SdkGenError } from '../utility'
+
+
+type PathSegment = {
+  lit?: string
+  var?: string
+}
+
+
+// The segment vector, defensively. GraphQL points address the single endpoint
+// and carry no path, so an empty vector is normal, not a fault.
+//
+// A point carrying the OLD `parts` and no `segments` is a different thing
+// entirely: a model generated by apidef <= 8.1, checked in under a project's
+// `.sdk/model/`, that has not been regenerated. Treating it as pathless
+// would emit an SDK whose every request goes to the API ROOT — silently,
+// because an empty path is indistinguishable from a GraphQL point here.
+//
+// THIS is where the check belongs. apidef 8.2.0 tried it in the schema
+// (`parts?: null`) and that bricked the upgrade instead: the stale model is
+// the INPUT to the tool that rewrites it, and voxgig-model unifies before it
+// runs apidef's build, so the file blocked its own regeneration. Here the
+// model unifies, apidef regenerates it, and a stale point only ever reaches
+// this helper when that regeneration did NOT happen — exactly when the
+// project needs to be told.
+function pointSegments(point: any): PathSegment[] {
+  const segments = point && point.segments
+
+  if (!Array.isArray(segments) && Array.isArray(point && point.parts)) {
+    throw new SdkGenError(
+      'model: the point for `' + ((point && point.orig) || '(unknown path)') +
+      '` still describes its path as `parts` (' +
+      JSON.stringify(point.parts) + ') and carries no `segments`. apidef ' +
+      'replaced the braced-string form with the typed segment vector in ' +
+      '8.2.0 (its ADR-003), so this model was generated by an older apidef ' +
+      'and has not been regenerated. Generating from it would build every ' +
+      'URL as the API root. Run `npm run generate` in the project\'s `.sdk` ' +
+      'so apidef rewrites its entity models, then generate again.')
+  }
+
+  return Array.isArray(segments) ? segments : []
+}
+
+
+// The braced-string form the SDK runtimes still consume. A `lit` is emitted
+// verbatim — including one that contains braces, which apidef leaves literal
+// (a compound element like `{a}.{b}` names no single parameter). That is the
+// lossiness ADR-003 removed from the model, and it survives here only because
+// this is the OLD representation being reconstructed on the way out.
+function pointParts(point: any): string[] {
+  return pointSegments(point).map((seg: PathSegment) =>
+    null == seg.var ? String(seg.lit ?? '') : '{' + seg.var + '}')
+}
+
+
+// Does the path end in a parameter?
+//
+// DELIBERATELY asked of the reconstructed part, not of the vector, even
+// though the vector states it directly and more accurately.
+//
+// The same rule runs at RUNTIME, in all 21 languages' makePoint template
+// (`0 === last.indexOf('{')` over `parts`), to pick a fallback route when no
+// point's `select.exist` matches. Those templates ship standalone, outside
+// this package, so the rule is written twice on purpose and BOTH SIDES MUST
+// MOVE TOGETHER — see the note in opShape.ts and in each template.
+//
+// Reading the vector here would break that. A path ending in a LITERAL that
+// contains braces (`/reports/{id}.json`) is not a terminal parameter by the
+// vector, but every runtime still says it is, because from the reconstructed
+// string it cannot tell. Generation-time `ownPoint` would then pick a
+// different route than the SDK picks at request time — for the same model.
+//
+// So this stays bug-compatible with the runtimes until they move onto
+// segments, at which point this becomes `null != last.var` and all 21 change
+// with it.
+function pointTerminalParam(point: any): boolean {
+  const parts = pointParts(point)
+  const last = 0 < parts.length ? parts[parts.length - 1] : ''
+  return 0 === last.indexOf('{')
+}
+
+
+// Do two points describe the same route? Compares the vectors, so a literal
+// containing braces cannot be mistaken for a parameter of the same spelling.
+function pointPathKey(point: any): string {
+  return pointSegments(point)
+    .map((seg: PathSegment) =>
+      null == seg.var ? 'l:' + String(seg.lit ?? '') : 'v:' + seg.var)
+    .join('/')
+}
+
+
+export type {
+  PathSegment,
+}
+
+export {
+  pointSegments,
+  pointParts,
+  pointTerminalParam,
+  pointPathKey,
+}

package/src/sdkgen.ts

@@ -67,6 +67,9 @@ import { serverVariables, hasServerVariables, serverVarEnv } from './helpers/ser
 import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
 import type { ExampleLang } from './helpers/opExample'
 import { liveStrict } from './helpers/testPolicy'
+import { pointSegments, pointParts, pointTerminalParam, pointPathKey }
+  from './helpers/pointPath'
+import type { PathSegment } from './helpers/pointPath'
 import {
   featureOf,
   availableFeatures,
@@ -1014,6 +1017,7 @@ export type {
   SdkGenOptions,
   ExampleLang,
   DepEntry,
+  PathSegment,
   FeatureSource,
   DoctorReport,
   RegisterOptions,
@@ -1119,6 +1123,13 @@ export {
   buildIdNames,
   getMatchEntries,
   collectDeps,
+
+  // apidef ADR-003: the model carries typed path segments, not braced
+  // strings. Scaffold components read the path through these.
+  pointSegments,
+  pointParts,
+  pointTerminalParam,
+  pointPathKey,
   canonToType,
   canonToDtype,
   canonKey,

package/src/utility.ts

@@ -8,6 +8,7 @@ import { KIT, getModelPath } from '@voxgig/apidef'
 import { targetFeatures } from './helpers/applicability'
 
 import { serverVariables } from './helpers/serverVars'
+import { pointParts } from './helpers/pointPath'
 import { packageVersion } from './helpers/packageMeta'
 
 
@@ -350,6 +351,35 @@ const SPEC_FACTS: Record<string, (model: any) => any> = {
 //
 // Key order is `each`'s order, which is sorted, so the JSON is byte-stable
 // across runs exactly like the literal it replaces.
+// The embedded config still speaks the braced-string path form
+// (`['element', '{id}']`) that every generated runtime reads. apidef now
+// emits the resolved vector instead (its ADR-003), so the old shape is
+// reconstructed HERE — the single point at which a point reaches generated
+// output — via the single reconstruction in helpers/pointPath.
+//
+// Both are written: `parts` for the runtimes as they stand, `segments`
+// alongside it so a runtime can be moved over one language at a time. That
+// duplication is deliberate and temporary, and it lives in GENERATED output,
+// not in the model — which is what ADR-003 forbids. It ends when the last
+// runtime reads segments and `parts` is dropped from this function.
+function withPointParts(op: any): any {
+  if (null == op) {
+    return op
+  }
+
+  const out: any = {}
+  each(op, (o: any, opname: string) => {
+    out[opname] = null == o || null == o.points ? o : {
+      ...o,
+      points: each(o.points).map((pt: any) =>
+        null == pt ? pt : { ...pt, parts: pointParts(pt) }),
+    }
+  })
+
+  return out
+}
+
+
 function configDefinition(model: any, targetname?: string): { def: any, json: string } {
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
@@ -377,7 +407,7 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
     entityDefs[e.name] = clean({
       fields: e.fields,
       name: e.name,
-      op: e.op,
+      op: withPointParts(e.op),
       relations: e.relations,
     }, true)
     entityStubs[e.name] = {}