@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/src/cmp/dart/fragment/Main.fragment.dart

@@ -1,338 +0,0 @@
-
-// ignore_for_file: non_constant_identifier_names
-
-import 'dart:async';
-
-import 'Config.dart';
-import 'Spec.dart';
-// ProjectNameEntityBase / ProjectNameError / BaseFeature are re-exported below;
-// a Dart `export` needs no matching `import`, so importing them here too is an
-// unused_import. Keep only the imports actually referenced in this file.
-import 'utility/ErrUtility.dart';
-// PREFIXED, and deliberately not re-exported. The runtime helper class is
-// named `Utility`, and so is the generated data class for an entity named
-// `utility` (ProjectNameTypes.dart) — exporting both from this library makes
-// the name ambiguous and NO dart SDK for such an API compiles:
-//
-//   Error: 'Utility' is exported from both 'lib/ProjectNameTypes.dart'
-//          and 'lib/utility/Utility.dart'
-//
-// The entity type is the user-facing name, so it keeps the plain one; the
-// runtime helper is internal plumbing and is reached through the prefix. Any
-// entity name can collide with an internal class, so the prefix — not a
-// rename — is what makes this safe for every API.
-import 'utility/Utility.dart' as sdkutil;
-
-export 'Config.dart' show Config, config;
-export 'ProjectNameEntityBase.dart' show ProjectNameEntityBase;
-export 'ProjectNameError.dart' show ProjectNameError;
-export 'feature/base/BaseFeature.dart' show BaseFeature;
-
-final sdkutil.Utility stdutil = sdkutil.Utility();
-
-class ProjectNameSDK {
-  String mode = 'live';
-  dynamic _options;
-  final sdkutil.Utility _utility = sdkutil.Utility();
-  List<dynamic> features = [];
-  dynamic rootctx;
-
-  // Feature activity tracking store (retry attempts, cache hits, spans, ...).
-  final Map<String, dynamic> track = {};
-
-  ProjectNameSDK([dynamic options]) {
-    rootctx = _utility.makeContext({
-      'client': this,
-      'utility': _utility,
-      'config': config.toMap(),
-      'options': options,
-      'shared': {},
-    });
-
-    _options = _utility.makeOptions(rootctx);
-
-    final struct = _utility.struct;
-
-    if (true == struct.getpath(_options, 'feature.test.active')) {
-      mode = 'test';
-    }
-
-    rootctx.options = _options;
-
-    features = [];
-
-    final featureAdd = _utility.featureAdd;
-    final featureInit = _utility.featureInit;
-
-    // Add features in the resolved order (makeOptions puts an explicit List
-    // order first, else defaults to test-first). Ordering matters: the
-    // `test` feature installs the base mock transport and the transport
-    // features (retry/cache/netsim/proxy/ratelimit) wrap whatever is current,
-    // so `test` must be added before them to sit at the base of the chain.
-    final List extendList =
-        _options['extend'] is List ? _options['extend'] : [];
-
-    final featureorder =
-        struct.getpath(_options, '__derived__.featureorder') ?? [];
-    for (final fname in featureorder) {
-      final fopts = _options['feature'][fname];
-      if (fopts is Map && true == fopts['active']) {
-        // An active name with no generated class is legal when an
-        // extend-supplied instance carries that name (station's adopt
-        // path): the instance is added below, positioned by its own
-        // __after__ entry, so skip it here rather than fail construction.
-        if (!config.hasFeature(fname.toString()) &&
-            extendList.any((f) => fname.toString() == f.name.toString())) {
-          continue;
-        }
-        featureAdd(rootctx, config.makeFeature(fname.toString()));
-      }
-    }
-
-    for (final f in extendList) {
-      featureAdd(rootctx, f);
-    }
-
-    for (final f in features) {
-      featureInit(rootctx, f);
-    }
-
-    final featureHook = _utility.featureHook;
-    featureHook(rootctx, 'PostConstruct');
-  }
-
-  dynamic options() {
-    return _utility.struct.clone(_options);
-  }
-
-  sdkutil.Utility utility() {
-    return _utility;
-  }
-
-  Future<dynamic> prepare([dynamic fetchargs]) async {
-    final utility = _utility;
-
-    final makeContext = utility.makeContext;
-    final makeFetchDef = utility.makeFetchDef;
-    final prepareHeaders = utility.prepareHeaders;
-    final prepareAuth = utility.prepareAuth;
-
-    fetchargs = fetchargs ?? {};
-
-    final ctx = makeContext({
-      'opname': 'prepare',
-      'ctrl': fetchargs['ctrl'] ?? {},
-    }, rootctx);
-
-    final options = _options;
-
-    // Build spec directly from SDK options + user-provided fetch args.
-    final spec = Spec({
-      'base': options['base'],
-      'prefix': options['prefix'],
-      'suffix': options['suffix'],
-      'path': fetchargs['path'] ?? '',
-      'method': fetchargs['method'] ?? 'GET',
-      'params': fetchargs['params'] ?? {},
-      'query': fetchargs['query'] ?? {},
-      'body': fetchargs['body'],
-      'step': 'start',
-    });
-
-    ctx.spec = spec;
-
-    spec.headers = prepareHeaders(ctx);
-
-    // Merge user-provided headers over SDK defaults.
-    if (fetchargs['headers'] is Map) {
-      (fetchargs['headers'] as Map).forEach((key, val) {
-        spec.headers[key] = val;
-      });
-    }
-
-    // Apply SDK auth (apikey, auth prefix, etc.)
-    final authResult = prepareAuth(ctx);
-    if (iserr(authResult)) {
-      return authResult;
-    }
-
-    return makeFetchDef(ctx);
-  }
-
-  // Raw endpoint access is operator-controllable, like every entity op.
-  // Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
-  // either one reaches the same endpoint.
-  Future<dynamic> direct([dynamic fetchargs]) async {
-    if (!_opAllowed('direct')) {
-      return _opDenied('direct');
-    }
-
-    return _rawRequest(fetchargs);
-  }
-
-  // Is this raw-access op permitted by the SDK's allow.op option?
-  bool _opAllowed(String op) {
-    final allow = _utility.struct.getpath(_options, 'allow.op');
-    return allow is String && allow.contains(op);
-  }
-
-  dynamic _opDenied(String op) {
-    final allow = _utility.struct.getpath(_options, 'allow.op');
-    return {
-      'ok': false,
-      'err': Exception('ProjectNameSDK: $op: operation not allowed by'
-          ' SDK option allow.op value: "${allow ?? ''}"'),
-    };
-  }
-
-  // Ungated request path shared by direct and graphql, each of which checks
-  // its own allow.op token first. Private, rather than a flag on fetchargs:
-  // a caller-supplied marker would let anyone opt straight back out of the
-  // gate by passing it.
-  Future<dynamic> _rawRequest([dynamic fetchargs]) async {
-    final utility = _utility;
-    final fetcher = utility.fetcher;
-    final makeContext = utility.makeContext;
-
-    final fetchdef = await prepare(fetchargs);
-    if (iserr(fetchdef)) {
-      return fetchdef;
-    }
-
-    final ctx = makeContext({
-      'opname': 'direct',
-      'ctrl': (fetchargs ?? {})['ctrl'] ?? {},
-    }, rootctx);
-
-    try {
-      final dynamic fetched =
-          await Future.value(fetcher(ctx, fetchdef['url'], fetchdef));
-
-      if (null == fetched) {
-        return {
-          'ok': false,
-          'err': ctx.error('direct_no_response', 'response: undefined')
-        };
-      } else if (iserr(fetched)) {
-        return {'ok': false, 'err': fetched};
-      }
-
-      final status = fetched['status'];
-
-      // No body responses (204 No Content, 304 Not Modified) and explicit
-      // zero content-length must skip JSON parsing.
-      final headers = fetched['headers'];
-      final contentLength =
-          headers is Map ? headers['content-length'] : null;
-      final noBody = 204 == status ||
-          304 == status ||
-          '0' == (null == contentLength ? null : contentLength.toString());
-
-      dynamic json;
-      if (!noBody) {
-        try {
-          final jsonFn = fetched['json'];
-          json = jsonFn is Function
-              ? await Future.value(jsonFn())
-              : fetched['json'];
-        } catch (_parseErr) {
-          // Body wasn't valid JSON — surface the raw response rather than
-          // throwing. data stays null; callers can inspect status/headers.
-          json = null;
-        }
-      }
-
-      return {
-        'ok': status is num && status >= 200 && status < 300,
-        'status': status,
-        'headers': fetched['headers'],
-        'data': json,
-      };
-    } catch (err) {
-      return {'ok': false, 'err': err};
-    }
-  }
-
-  // Raw GraphQL access: the pressure valve that makes the generated
-  // surface's deliberate omissions (per-call selection sets, typed filter
-  // builders, batching, subscriptions) livable — the whole schema stays
-  // reachable.
-  //
-  // Thin wrapper over the same prepare/fetch path direct uses, with the one
-  // thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP 200
-  // as a top-level `errors` array, so status alone would report a failed
-  // query as ok.
-  //
-  // NOTE: like direct, this bypasses the feature pipeline — no retry,
-  // ratelimit or paging features apply.
-  Future<dynamic> graphql(String query,
-      [dynamic variables, dynamic ctrl]) async {
-    if (!_opAllowed('graphql')) {
-      return _opDenied('graphql');
-    }
-
-    final dynamic res = await _rawRequest({
-      'method': 'POST',
-      'headers': {'content-type': 'application/json'},
-      'body': {'query': query, 'variables': variables ?? {}},
-      'ctrl': ctrl ?? {},
-    });
-
-    if (res is! Map) {
-      return res;
-    }
-
-    // Errors are read BEFORE any status check: a GraphQL parse or validation
-    // failure comes back as HTTP 400 carrying the standard { errors: [...] }
-    // body, and the raw path represents a non-2xx as ok:false with no err —
-    // so returning early on status would discard the server's own
-    // diagnostics, which are the only useful part of that response.
-    final errors = _utility.struct.getpath(res, 'data.errors');
-
-    if (errors is List && 0 < errors.length) {
-      final first = errors[0];
-      final msg = (first is Map ? first['message'] : null);
-      res['ok'] = false;
-      res['err'] = Exception('ProjectNameSDK: graphql: '
-          '${msg is String && msg.isNotEmpty ? msg : 'graphql error'}');
-      res['graphql'] = errors;
-    }
-
-    return res;
-  }
-
-  // <[SLOT]>
-
-  static ProjectNameSDK test([dynamic testoptsarg, dynamic sdkoptsarg]) {
-    final struct = stdutil.struct;
-    final setpath = struct.setpath;
-    final getdef = struct.getdef;
-    final clone = struct.clone;
-    final setprop = struct.setprop;
-
-    final sdkopts = getdef(clone(sdkoptsarg), {});
-    final testopts = getdef(clone(testoptsarg), {});
-    setprop(testopts, 'active', true);
-    setpath(sdkopts, 'feature.test', testopts);
-
-    final testsdk = ProjectNameSDK(sdkopts);
-    testsdk.mode = 'test';
-
-    return testsdk;
-  }
-
-  ProjectNameSDK tester([dynamic testopts, dynamic sdkopts]) {
-    return ProjectNameSDK.test(testopts, sdkopts);
-  }
-
-  Map<String, dynamic> toJSON() {
-    return {'name': 'ProjectName'};
-  }
-
-  @override
-  String toString() {
-    return 'ProjectName ' + _utility.struct.jsonify(toJSON());
-  }
-}
-
-typedef SDK = ProjectNameSDK;

package/project/.sdk/src/cmp/dart/fragment/SdkError.fragment.dart

@@ -1,26 +0,0 @@
-class ProjectNameError extends Error {
-  final bool isProjectNameError = true;
-
-  final String sdk = 'ProjectName';
-
-  String code;
-  String message;
-  dynamic ctx;
-
-  // Populated by makeError with the (cleaned) result and spec.
-  dynamic result;
-  dynamic spec;
-
-  // HTTP status of the response that caused this error, or -1 when the
-  // request never got one. PROMOTED to the top level: it used to be
-  // reachable only at `err.result['status']`, so every consumer coupled
-  // itself to the internal shape of `result`.
-  int status = -1;
-
-  bool get notFound => 404 == status;
-
-  ProjectNameError(this.code, this.message, [this.ctx]);
-
-  @override
-  String toString() => 'ProjectNameError: ' + code + ': ' + message;
-}

package/project/.sdk/src/cmp/dart/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "esModuleInterop": true,
-    "module": "nodenext",
-    "noEmitOnError": true,
-    "outDir":"../dist",
-    "rootDir":".",
-    "resolveJsonModule": true,
-    "sourceMap": true,
-    "strict": true,
-    "target": "es2022",
-    "declaration": true,
-    "declarationDir": "../dist"
-  }
-}

package/project/.sdk/src/cmp/dart/utility_dart.ts

@@ -1,155 +0,0 @@
-
-import * as Path from 'node:path'
-
-
-import {
-  clone,
-  walk,
-} from '@voxgig/struct'
-
-
-// Escape a string for a single-quoted Dart string literal. `$` must be
-// escaped or Dart interpolates it (model values like '`$COPY`' would break).
-function dartString(s: string): string {
-  return "'" + String(s)
-    .replace(/\\/g, '\\\\')
-    .replace(/'/g, "\\'")
-    .replace(/\$/g, '\\$')
-    .replace(/\n/g, '\\n')
-    .replace(/\r/g, '\\r')
-    .replace(/\t/g, '\\t') + "'"
-}
-
-
-// Render a JSON-like value as a deep-dynamic Dart literal. Every map is
-// emitted as `<String, dynamic>{...}` and every list as `<dynamic>[...]` so
-// the runtime struct utilities can freely mutate/extend the structures
-// (inferred literal types would be too narrow and throw at runtime).
-function dartValue(obj: any, indent: number = 0): string {
-  const pad = '  '.repeat(indent)
-  const cpad = '  '.repeat(indent + 1)
-
-  if (null == obj) {
-    return 'null'
-  }
-  if ('string' === typeof obj) {
-    return dartString(obj)
-  }
-  if ('number' === typeof obj) {
-    return isFinite(obj) ? String(obj) : 'null'
-  }
-  if ('boolean' === typeof obj) {
-    return obj ? 'true' : 'false'
-  }
-  if (Array.isArray(obj)) {
-    if (0 === obj.length) {
-      return '<dynamic>[]'
-    }
-    return '<dynamic>[\n' +
-      obj.map(v => cpad + dartValue(v, indent + 1) + ',').join('\n') +
-      '\n' + pad + ']'
-  }
-  if ('object' === typeof obj) {
-    const keys = Object.keys(obj)
-    if (0 === keys.length) {
-      return '<String, dynamic>{}'
-    }
-    return '<String, dynamic>{\n' +
-      keys.map(k => cpad + dartString(k) + ': ' + dartValue(obj[k], indent + 1) + ',')
-        .join('\n') +
-      '\n' + pad + '}'
-  }
-  return 'null'
-}
-
-
-function projectPath(suffix?: string): string {
-  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
-}
-
-
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
-const MODEL_META = ['index$', 'key$', 'val$']
-
-// Keys whose value IS the default the runtime already assumes when the key is
-// absent, so emitting them is pure payload.
-const CONFIG_DEFAULT: Record<string, any> = {
-  active: true,
-  req: false,
-  reqd: false,
-}
-
-// Subtrees carrying user payload rather than schema. An active:true inside an
-// OpenAPI example is DATA, not a default, so default-pruning stops at these
-// keys and everything below them is passed through untouched.
-const PAYLOAD_KEYS = ['default', 'example', 'examples']
-
-function clean(o: any, dropDefaults?: boolean): any {
-  const prune = (node: any, defaults: boolean): any => {
-    if (Array.isArray(node)) {
-      return node.map((n: any) => prune(n, defaults))
-    }
-    if (null != node && 'object' === typeof node) {
-      const out: any = {}
-      for (const k of Object.keys(node)) {
-        if (MODEL_META.includes(k)) {
-          continue
-        }
-        if (defaults && k in CONFIG_DEFAULT && CONFIG_DEFAULT[k] === node[k]) {
-          continue
-        }
-        out[k] = prune(node[k], defaults && !PAYLOAD_KEYS.includes(k))
-      }
-      return out
-    }
-    return node
-  }
-  return prune(o, true === dropDefaults)
-}
-
-
-
-// The JSON as a Dart string literal.
-//
-// Dart's ordinary string literals INTERPOLATE: `$name` and `${...}` are
-// substitution, and the model is full of `$` - `$STRING`, `$NUMBER`,
-// `$action`. A raw string (`r'...'`) would avoid that but cannot contain its
-// own quote character and has no escape for it, and the JSON contains both
-// quote characters in quantity.
-//
-// So: JSON.stringify's escaping, which already handles `"` and `\` and emits
-// no raw control characters, plus `$` -> `\$`. That last step is unambiguous
-// precisely because JSON.stringify has already escaped every backslash, so a
-// `\$` here can only have come from this rule.
-function dartStringLiteral(json: string): string {
-  return JSON.stringify(json).replace(/\$/g, '\\$')
-}
-
-export {
-  dartStringLiteral,
-  clean,
-  dartString,
-  dartValue,
-  projectPath,
-}

package/project/.sdk/src/cmp/lean/Config_lean.ts

@@ -1,93 +0,0 @@
-import {
-  Content,
-  File,
-  cmp,
-  each,
-  isAuthActive,
-  resolveAuthPrefix,
-  targetFeatures,
-  configDefinition,
-} from '@voxgig/sdkgen'
-
-import {
-  KIT,
-  Model,
-  getModelPath,
-} from '@voxgig/apidef'
-
-import {
-  leanString,
-} from './utility_lean'
-
-
-// SdkConfig.lean: the embedded API model, serialised to a JSON string. The
-// config-driven runtime (SdkRuntime) parses it into a struct `Value` at client
-// construction — the whole SDK is data-driven, so there is no per-entity code.
-const Config = cmp(async function Config(props: any) {
-  const ctx$ = props.ctx$
-  const target = props.target
-
-  const model: Model = ctx$.model
-
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const { def: configDef } = configDefinition(model, target.name)
-  // Gated by the applicability tags, so this target never imports or
-  // registers a feature it has no source for. One rule, one place:
-  // helpers/applicability.
-  const feature = targetFeatures(model, target)
-  const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
-
-  const authActive = isAuthActive(model)
-  const authPrefix = resolveAuthPrefix(model)
-
-  let baseUrl = ''
-  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
-
-  const featureConfig: any = {}
-  each(feature, (f: any) => { featureConfig[f.name] = f.config || {} })
-
-  const entityOptions: any = {}
-  each(entity, (ent: any) => { entityOptions[ent.name] = {} })
-
-  const options: any = {
-    base: baseUrl,
-    headers,
-    entity: entityOptions,
-  }
-  if (authActive) {
-    options.auth = { prefix: authPrefix }
-  }
-
-  // configDefinition's `def.entity` verbatim, NOT rebuilt here. This reduce
-  // was one of fourteen copies of that function's entityDefs loop, and when
-  // configDefinition started reconstructing a point's `parts` from apidef's
-  // segment vector (its ADR-003), only the copies that read `configDef` got
-  // it — this target's literal config emitted paths with no parts at all
-  // while its data config had them. One rule, one place.
-  const entityConfig = configDef.entity
-
-  const config = {
-    main: { name: model.const.Name },
-    feature: featureConfig,
-    options,
-    entity: entityConfig,
-  }
-
-  File({ name: 'SdkConfig.' + target.ext }, () => {
-    Content(`-- Generated API configuration for the config-driven runtime.
--- The embedded model is parsed into a struct Value at client construction.
-
-namespace SdkConfig
-
-def configJson : String :=
-  ${leanString(JSON.stringify(config))}
-
-end SdkConfig
-`)
-  })
-})
-
-
-export {
-  Config
-}

package/project/.sdk/src/cmp/lean/Entity_lean.ts

@@ -1,9 +0,0 @@
-import { cmp } from '@voxgig/sdkgen'
-
-// Entities are generic in the Lean target: there is no per-entity generated
-// module. Every entity's operations are dispatched by the config-driven
-// SdkRuntime (see SdkClient), so this component emits nothing. It exists only
-// so the neutral Entity component can resolve a language delegate.
-const Entity = cmp(function Entity(_props: any) {})
-
-export { Entity }

package/project/.sdk/src/cmp/lean/Gitignore_lean.ts

@@ -1,18 +0,0 @@
-import { Content, File, cmp } from '@voxgig/sdkgen'
-
-const Gitignore = cmp(async function Gitignore(_props: any) {
-  File({ name: '.gitignore' }, () => {
-    Content(`# Lake build output
-.lake/
-build/
-lake-packages/
-
-# IDE / OS
-.idea/
-.vscode/
-.DS_Store
-`)
-  })
-})
-
-export { Gitignore }