@voxgig/sdkgen 1.3.18 → 1.3.19

package/src/helpers/naming.ts

@@ -126,6 +126,75 @@ function rbSafeTypeName(Name: string): string {
 }
 
 
+// Swift SDK-OWNED TYPE NAMES — a third hazard, distinct from both sets above.
+//
+// The keyword sets guard local bindings; the Ruby set guards clobbering the
+// LANGUAGE's core. This set guards clobbering OUR OWN runtime, because Swift
+// has no namespacing WITHIN a module: every type the swift templates declare
+// and every generated entity type land in the same module. Two declarations
+// of one name is a hard error, not a silent override:
+//
+//   // core/Response.swift  (template)
+//   public final class Response { ... }      // transport wrapper
+//   // entity/<Prefix>Types.swift  (generated from a spec schema named Response)
+//   public struct Response { ... }
+//   -> error: invalid redeclaration of 'Response'
+//   -> error: 'Response' is ambiguous for type lookup   (every core file)
+//
+// Found 2026-08-07: the Hook0 spec has a `Response` schema, which took the
+// whole swift target down. `Response` is merely the first collision to be
+// hit — every name below is equally exposed.
+//
+// Sourced by scanning BOTH `tm/swift/Sources/*/` (templates) and
+// `src/cmp/swift/*.ts` (components) for top-level type declarations —
+// regardless of access level. `internal` is Swift's default and is still
+// module-wide, and `open class BaseFeature` is not `public` either, so an
+// access-level filter under-collects and silently reopens the bug.
+//
+// Nested types (a `typealias Element` inside a struct) and the separate Tests
+// module (`ReadmeExamplesTest`) do NOT share this namespace and are excluded.
+//
+// `swift-sdk-types.test.ts` re-derives this list from the templates and fails
+// on drift, so adding a public type to a swift template cannot silently
+// reopen the bug.
+const SWIFT_SDK_TYPES = new Set<string>([
+  // core runtime
+  'Context', 'Control', 'Entity', 'Operation', 'Point', 'Response', 'Result',
+  'SdkConfig', 'Spec', 'Utility',
+  // struct library
+  'Injection', 'Injector', 'JSON', 'JSONParseError', 'Modify',
+  'OrderedDictionary', 'Sentinel', 'Value', 'VList', 'VMap', 'WalkApply',
+  // function/callback aliases
+  'FetcherFunc', 'Formatter', 'NativeCall0', 'NativeRef', 'SystemFetch',
+  // features
+  'AuditFeature', 'BaseFeature', 'CacheFeature', 'ClienttrackFeature',
+  'DebugFeature', 'IdempotencyFeature', 'LogFeature', 'MetricsBucket',
+  'MetricsFeature', 'NetsimFeature', 'PagingFeature', 'ProxyFeature',
+  'RatelimitFeature', 'RbacFeature', 'RetryFeature', 'StreamingFeature',
+  'TelemetryFeature', 'TestFeature', 'TimeoutFeature',
+])
+
+
+// Does `Name` collide with a type the swift SDK runtime already declares?
+function isSwiftSdkType(Name: string): boolean {
+  return SWIFT_SDK_TYPES.has(Name)
+}
+
+
+// A module-safe Swift type name for a generated type: unchanged, unless the
+// swift runtime already declares it, in which case `Type` is appended
+// (`Response` -> `ResponseType`). Mirrors rbSafeTypeName deliberately — same
+// suffix, same "only rename on an actual collision" rule, so SDKs that do not
+// collide are byte-identical to before.
+//
+// Applied ONLY to the bare entity data type. Per-op type names already carry
+// their own suffix (`ResponseCreateData`, `ResponseLoadMatch`) and the entity
+// CLASS is separately suffixed (`ResponseEntity`), so neither ever collided.
+function swiftSafeTypeName(Name: string): string {
+  return isSwiftSdkType(Name) ? Name + 'Type' : Name
+}
+
+
 // Is `name` a reserved word (an illegal identifier) in the target language?
 function isReservedName(name: string, lang: string): boolean {
   const set = RESERVED[lang]
@@ -189,6 +258,8 @@ export {
   exampleVarName,
   isRbCoreConstant,
   rbSafeTypeName,
+  isSwiftSdkType,
+  swiftSafeTypeName,
   jsProp,
   jsOptProp,
   jsKey,

package/src/helpers/serverVars.ts

@@ -0,0 +1,105 @@
+// OpenAPI server-variable support (templated server URLs).
+//
+// A spec may declare its server URL as a template over named variables:
+//
+//   servers:
+//     - url: https://{tenant_id}.hanko.io
+//       variables:
+//         tenant_id: { default: '', description: '...' }
+//
+// The generated SDKs carry the template verbatim in `options.base` and
+// resolve it AT CONSTRUCTION via the `server` options block:
+//
+//   new SDK({ server: { tenant_id: 'my-tenant' } })
+//
+// Resolution rules (identical in every target runtime):
+//   - each `{name}` in base is replaced with options.server[name],
+//     falling back to the spec default emitted into the SDK's Config;
+//   - a variable that resolves to '' is an ERROR at construction — the
+//     URL cannot work without it — EXCEPT in test mode, where the
+//     deterministic value `test-<name>` is substituted so offline tests
+//     never require configuration.
+//
+// This module is the emission-side half: it parses the spec's variables
+// out of the model so Config emitters can write the `server` defaults
+// block, and docs can name the required variables.
+
+// One declared server variable. `required` is true when the spec gives no
+// usable default — the caller MUST supply it for live use.
+type ServerVar = {
+  name: string
+  dflt: string
+  required: boolean
+  description: string
+}
+
+
+// Match {name} placeholders in a server URL template. OpenAPI variable
+// names are restricted to word characters in practice; a brace group that
+// is not a well-formed name is left untouched rather than guessed at.
+const SERVER_VAR_RE = /\{([A-Za-z0-9_]+)\}/g
+
+
+// Parse the server variables declared on servers[0] of the model
+// (main.<KIT>.info.servers.0). Variables are returned in URL order —
+// the order their placeholders appear in the template — with declared
+// variables that never appear in the URL appended after (harmless, but
+// kept so docs can still describe them). Returns [] when the URL has no
+// placeholders.
+function serverVariables(model: any): ServerVar[] {
+  const info = model?.main?.kit?.info || model?.main?.KIT?.info
+  const server = info?.servers?.[0]
+  const url: string = server?.url || ''
+  const declared = server?.variables || {}
+
+  const out: ServerVar[] = []
+  const seen = new Set<string>()
+
+  SERVER_VAR_RE.lastIndex = 0
+  let m: RegExpExecArray | null
+  while (null != (m = SERVER_VAR_RE.exec(url))) {
+    const name = m[1]
+    if (seen.has(name)) { continue }
+    seen.add(name)
+    const decl = declared[name] || {}
+    const dflt = 'string' === typeof decl.default ? decl.default : ''
+    out.push({
+      name,
+      dflt,
+      required: '' === dflt,
+      description: 'string' === typeof decl.description ? decl.description : '',
+    })
+  }
+
+  // Declared-but-unreferenced variables: not substitutable, never required.
+  for (const name of Object.keys(declared)) {
+    if (seen.has(name)) { continue }
+    seen.add(name)
+    const decl = declared[name] || {}
+    out.push({
+      name,
+      dflt: 'string' === typeof decl.default ? decl.default : '',
+      required: false,
+      description: 'string' === typeof decl.description ? decl.description : '',
+    })
+  }
+
+  return out
+}
+
+
+// Does the model's server URL contain any {name} placeholders at all?
+function hasServerVariables(model: any): boolean {
+  const info = model?.main?.kit?.info || model?.main?.KIT?.info
+  const url: string = info?.servers?.[0]?.url || ''
+  SERVER_VAR_RE.lastIndex = 0
+  return SERVER_VAR_RE.test(url)
+}
+
+
+export {
+  serverVariables,
+  hasServerVariables,
+}
+
+export type { ServerVar }

package/src/sdkgen.ts

@@ -52,7 +52,8 @@ import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, 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, jsProp, jsOptProp, jsKey } from './helpers/naming'
+import { isReservedName, safeVarName, exampleVarName, isRbCoreConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
+import { serverVariables, hasServerVariables } from './helpers/serverVars'
 import {
   packageName,
   installCommand,
@@ -480,6 +481,10 @@ export {
   exampleVarName,
   isRbCoreConstant,
   rbSafeTypeName,
+  isSwiftSdkType,
+  swiftSafeTypeName,
+  serverVariables,
+  hasServerVariables,
   jsProp,
   jsOptProp,
   jsKey,