@voxgig/sdkgen-langpack 0.0.1

package/.sdk/src/cmp/dart/Test_dart.ts

@@ -0,0 +1,138 @@
+
+import {
+  nom,
+} from '@voxgig/apidef'
+
+import type {
+  ModelEntity
+} from '@voxgig/apidef'
+
+import { cmp, each, snakify, Folder, File, Content, entityCollection,
+  targetFeatures, TestControl } from '@voxgig/sdkgen'
+
+
+import { TestDirect } from './TestDirect_dart'
+import { TestEntity } from './TestEntity_dart'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_dart'
+
+
+const Test = cmp(function Test(props: any) {
+  const { model } = props.ctx$
+  const { target } = props
+
+  const entity = each(entityCollection(model))
+    .filter((e: any) => false !== e.active)
+
+  // GATED SUITES. test/main.dart is a HAND-LISTED suite entry - dart has no
+  // `go test ./...` or pytest discovery - so a feature whose tests ship in
+  // its own trimmable folder has to be registered here or it is dead
+  // weight. Both halves matter, and they fail in opposite directions:
+  // register unconditionally and a project without the feature imports a
+  // file that is not there (a compile error); forget to register and the
+  // suite ships, never runs, and the lane stays green while nothing is
+  // checked. The feature list is tag-gated, so a target with no vendored
+  // sekreto never reaches this.
+  const feature = targetFeatures(model, target)
+  const secrets = null != feature.secrets
+
+  Folder({ name: 'test' }, () => {
+
+    // Write-once: a project's edited control file survives regeneration.
+    TestControl({ target, dir: 'test' })
+
+    // Suite entry: registers every static suite plus the generated
+    // per-entity suites, then runs them (Makefile: dart run test/main.dart).
+    File({ name: 'main.' + target.ext }, () => {
+
+      Content(`// ${model.const.Name} SDK test suite entry. GENERATED — do not edit.
+
+import 'dart:io';
+
+import 'harness.dart' as harness;
+
+import 'exists_test.dart' as exists_test;
+import 'omni_smoke_test.dart' as omni_smoke_test;
+import 'struct_test.dart' as struct_test;
+import 'primary_test.dart' as primary_test;
+import 'pipeline_test.dart' as pipeline_test;
+import 'feature_test.dart' as feature_test;
+import 'netsim_test.dart' as netsim_test;
+import 'custom_test.dart' as custom_test;
+import 'readme_examples_test.dart' as readme_examples_test;
+`)
+
+      if (secrets) {
+        Content(`import 'feature/secrets/secrets_test.dart' as secrets_test;
+`)
+      }
+
+      each(entity, (ent: ModelEntity) => {
+        const alias = snakify(ent.name)
+        Content(`import 'entity/${ent.name}/${nom(ent, 'Name')}Entity_test.dart' as ${alias}_entity_test;
+`)
+        if (hasDirect(ent)) {
+          Content(`import 'entity/${ent.name}/${nom(ent, 'Name')}Direct_test.dart' as ${alias}_direct_test;
+`)
+        }
+      })
+
+      Content(`
+Future<void> main() async {
+  exists_test.tests();
+  omni_smoke_test.tests();
+  struct_test.tests();
+  primary_test.tests();
+  pipeline_test.tests();
+  feature_test.tests();
+  netsim_test.tests();
+  custom_test.tests();
+  readme_examples_test.tests();
+`)
+
+      if (secrets) {
+        Content(`  secrets_test.tests();
+`)
+      }
+
+      each(entity, (ent: ModelEntity) => {
+        const alias = snakify(ent.name)
+        Content(`  ${alias}_entity_test.tests();
+`)
+        if (hasDirect(ent)) {
+          Content(`  ${alias}_direct_test.tests();
+`)
+        }
+      })
+
+      Content(`
+  final failed = await harness.runAll();
+  if (0 < failed) {
+    exitCode = 1;
+  }
+}
+`)
+    })
+
+    // Documentation dart-examples presence & completeness gate.
+    ReadmeExamplesTest({ target })
+
+    Folder({ name: 'entity' }, () => {
+      each(entity, (ent: ModelEntity) => {
+        TestEntity({ target, entity: ent })
+        TestDirect({ target, entity: ent })
+      })
+    })
+  })
+})
+
+
+// A Direct test file is generated only when the entity has load or list.
+function hasDirect(entity: any): boolean {
+  const opnames = Object.keys(entity.op || {})
+  return opnames.includes('load') || opnames.includes('list')
+}
+
+
+export {
+  Test
+}

package/.sdk/src/cmp/dart/fragment/Config.data.fragment.dart

@@ -0,0 +1,98 @@
+import 'dart:convert';
+
+import 'feature/base/BaseFeature.dart';
+// #ImportFeatures
+// #ImportPlugins
+
+// ignore: non_constant_identifier_names
+final Map<String, BaseFeature Function()> FEATURE_CLASS = {
+  // #FeatureClasses
+};
+
+// Per-feature plugin DEFINITIONS (voxgig/plugin `Definition` values), from
+// the model's active plugin groups. A feature that takes a `plugins` option
+// (secrets over sekreto) reads its own entry; a feature with no plugins has
+// none. The named `show` imports above make each definition statically
+// reachable, so an SDK carries exactly the plugin libraries its model
+// selects - the same leanness the old side-effect registry bought, without
+// a registry.
+//
+// Emitted UNCONDITIONALLY, empty when no group is active: SecretsFeature
+// imports this name, and the feature source can be present in a tree whose
+// model selects no plugin group at all. An emission conditional on the map
+// having entries would make that tree fail `dart analyze`.
+//
+// ignore: non_constant_identifier_names
+final Map<String, List<dynamic>> FEATURE_PLUGINS = <String, List<dynamic>>{
+  // #FeaturePlugins
+};
+
+// THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+//
+// The literal form of this file declares the whole model as nested map
+// literals. For a large API that is megabytes of source the Dart analyzer and
+// compiler must parse and type every node of, on every build, and that the VM
+// must build entry by entry on every load.
+//
+// As a single string constant it is one token, and `jsonDecode` builds the map
+// far faster than the equivalent literal.
+//
+// Emitted only above a size threshold, or when `main.kit.config.repr` pins it:
+// for a small model the literal is smaller, loads no slower, and is far easier
+// to read when debugging.
+const String _CONFIG_DATA = 'CONFIGJSON';
+
+class Config {
+  // ONE decode per constructed Config, and each instance owns the maps it
+  // decoded. The literal representation builds fresh maps in every field
+  // initialiser, so a caller that constructs a second Config and mutates it
+  // does not touch the first - and `Config` is exported by Main.fragment.dart,
+  // so callers really can construct one.
+  //
+  // Sharing a single top-level parsed map would have been cheaper and was the
+  // first attempt; it made `Config().options['x'] = 1` mutate the `config`
+  // singleton every SDK client reads. Decoding per instance costs about what
+  // building the literal per instance cost, and the rung's win is untouched:
+  // L1 is about what the COMPILER has to walk, not what happens at load.
+  Config() : this._(jsonDecode(_CONFIG_DATA) as Map<String, dynamic>);
+
+  Config._(Map<String, dynamic> data)
+      : main = data['main'] as Map<String, dynamic>,
+        feature = data['feature'] as Map<String, dynamic>,
+        options = data['options'] as Map<String, dynamic>,
+        entity = data['entity'] as Map<String, dynamic>;
+
+  BaseFeature makeFeature(String fn) {
+    final fc = FEATURE_CLASS[fn];
+    if (null == fc) {
+      // TODO: errors etc
+      throw StateError('Unknown feature: ' + fn);
+    }
+    return fc();
+  }
+
+  // False for a feature added at runtime via options.extend (station's
+  // adopt path) - the constructor uses this to skip makeFeature for names
+  // no generated class backs.
+  bool hasFeature(String fn) => null != FEATURE_CLASS[fn];
+
+  // The same fields the literal declares - same names, same types, same
+  // finalness - so callers cannot tell which representation they were given.
+  final Map<String, dynamic> main;
+
+  final Map<String, dynamic> feature;
+
+  final Map<String, dynamic> options;
+
+  final Map<String, dynamic> entity;
+
+  // The pipeline context carries the config as a plain map.
+  Map<String, dynamic> toMap() => <String, dynamic>{
+        'main': main,
+        'feature': feature,
+        'options': options,
+        'entity': entity,
+      };
+}
+
+final config = Config();

package/.sdk/src/cmp/dart/fragment/Config.fragment.dart

@@ -0,0 +1,70 @@
+import 'feature/base/BaseFeature.dart';
+// #ImportFeatures
+// #ImportPlugins
+
+// ignore: non_constant_identifier_names
+final Map<String, BaseFeature Function()> FEATURE_CLASS = {
+  // #FeatureClasses
+};
+
+// Per-feature plugin DEFINITIONS (voxgig/plugin `Definition` values), from
+// the model's active plugin groups. A feature that takes a `plugins` option
+// (secrets over sekreto) reads its own entry; a feature with no plugins has
+// none. The named `show` imports above make each definition statically
+// reachable, so an SDK carries exactly the plugin libraries its model
+// selects - the same leanness the old side-effect registry bought, without
+// a registry.
+//
+// Emitted UNCONDITIONALLY, empty when no group is active: SecretsFeature
+// imports this name, and the feature source can be present in a tree whose
+// model selects no plugin group at all. An emission conditional on the map
+// having entries would make that tree fail `dart analyze`.
+//
+// ignore: non_constant_identifier_names
+final Map<String, List<dynamic>> FEATURE_PLUGINS = <String, List<dynamic>>{
+  // #FeaturePlugins
+};
+
+class Config {
+  BaseFeature makeFeature(String fn) {
+    final fc = FEATURE_CLASS[fn];
+    if (null == fc) {
+      // TODO: errors etc
+      throw StateError('Unknown feature: ' + fn);
+    }
+    return fc();
+  }
+
+  // False for a feature added at runtime via options.extend (station's
+  // adopt path) - the constructor uses this to skip makeFeature for names
+  // no generated class backs.
+  bool hasFeature(String fn) => null != FEATURE_CLASS[fn];
+
+  final Map<String, dynamic> main = <String, dynamic>{
+    'name': 'ProjectName',
+    // #MainMeta
+  };
+
+  final Map<String, dynamic> feature = <String, dynamic>{
+    // #FeatureConfigs
+  };
+
+  // Rendered whole from the canonical config definition rather than assembled
+  // slot by slot. Assembling it here meant `options.server` - the OpenAPI
+  // server-variable defaults - was simply absent from this branch, so a
+  // templated server URL produced a different config either side of the
+  // threshold.
+  final Map<String, dynamic> options = 'OPTIONSMAP';
+
+  final Map<String, dynamic> entity = 'ENTITYMAP';
+
+  // The pipeline context carries the config as a plain map.
+  Map<String, dynamic> toMap() => <String, dynamic>{
+        'main': main,
+        'feature': feature,
+        'options': options,
+        'entity': entity,
+      };
+}
+
+final config = Config();

package/.sdk/src/cmp/dart/fragment/Direct.test.fragment.dart

@@ -0,0 +1,25 @@
+// ignore_for_file: unused_import, unused_local_variable, non_constant_identifier_names
+
+import 'dart:convert';
+
+import '../../harness.dart';
+import '../../utility.dart';
+
+import '../../../lib/ProjectNameSDK.dart';
+
+void tests() {
+  describe('EntityNameDirect', () {
+    test('direct-exists', (t) async {
+      final sdk = ProjectNameSDK({
+        'system': {
+          'fetch': (dynamic url, dynamic init) async => <String, dynamic>{}
+        }
+      });
+      ok(null != sdk);
+    });
+
+    // <[SLOT:direct]>
+  });
+}
+
+// <[SLOT:directSetup]>

package/.sdk/src/cmp/dart/fragment/Entity.fragment.dart

@@ -0,0 +1,29 @@
+
+// ignore_for_file: non_constant_identifier_names
+
+// #OpImports
+import '../ProjectNameEntityBase.dart';
+
+// #TypeImports
+
+class EntyClass extends ProjectNameEntityBase {
+  EntyClass(dynamic client, dynamic entopts) : super(client, entopts) {
+    name = 'entityname';
+    name_ = 'entityname';
+    Name = 'EntityName';
+  }
+
+  EntyClass make() {
+    return EntyClass(client, entopts());
+  }
+
+  // #LoadOp
+
+  // #ListOp
+
+  // #CreateOp
+
+  // #UpdateOp
+
+  // #RemoveOp
+}

package/.sdk/src/cmp/dart/fragment/Entity.test.fragment.dart

@@ -0,0 +1,28 @@
+// ignore_for_file: unused_import, unused_local_variable, non_constant_identifier_names
+
+import 'dart:convert';
+import 'dart:io';
+
+import '../../harness.dart';
+import '../../utility.dart';
+
+import '../../../lib/ProjectNameSDK.dart';
+import '../../../lib/utility/voxgig_struct.dart' as vs;
+
+void tests() {
+  describe('EntityNameEntity', () {
+    test('instance', (t) async {
+      final testsdk = ProjectNameSDK.test();
+      final ent = testsdk.EntityName();
+      ok(null != ent);
+    });
+
+    // <[SLOT:stream]>
+
+    test('basic', (t) async {
+      // <[SLOT:basic]>
+    });
+  });
+}
+
+// <[SLOT:basicSetup]>

package/.sdk/src/cmp/dart/fragment/EntityBase.fragment.dart

@@ -0,0 +1,302 @@
+
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+
+import 'utility/ErrUtility.dart';
+
+// Base class for generated entities. `dataVal`/`matchVal` hold accreted
+// partial state (they start {} and fill in as ops resolve); the full typed
+// data models are documented in ProjectNameTypes.dart.
+class ProjectNameEntityBase {
+  String name = '';
+  String name_ = '';
+  String Name = '';
+
+  dynamic client;
+  dynamic utility;
+  dynamic entoptsMap;
+  dynamic dataVal = {};
+  dynamic matchVal = {};
+  dynamic entctx;
+
+  ProjectNameEntityBase(dynamic client_, dynamic entopts_) {
+    final entopts = entopts_ ?? {};
+    if (entopts is Map) {
+      entopts['active'] = false != entopts['active'];
+    }
+
+    client = client_;
+    entoptsMap = entopts;
+    utility = client_.utility();
+    dataVal = {};
+    matchVal = {};
+
+    final makeContext = utility.makeContext;
+
+    entctx = makeContext({
+      'entity': this,
+      'entopts': entopts,
+    }, client_.rootctx);
+
+    final featureHook = utility.featureHook;
+    featureHook(entctx, 'PostConstructEntity');
+  }
+
+  // Every operation resolves to the entity; `remove` additionally marks
+  // it. The instance KEEPS the data it held — a caller can still read what
+  // was deleted — but it is no longer a live record. See AGENTS.md.
+  bool _deleted = false;
+
+  void markDeleted() {
+    _deleted = true;
+  }
+
+  bool deleted() => _deleted;
+
+
+  dynamic entopts() {
+    return utility.struct.merge([{}, entoptsMap]);
+  }
+
+  dynamic data([dynamic d]) {
+    final struct = utility.struct;
+    final featureHook = utility.featureHook;
+
+    if (null != d) {
+      dataVal = struct.clone(d);
+      featureHook(entctx, 'SetData');
+    }
+
+    featureHook(entctx, 'GetData');
+    final out = struct.clone(dataVal);
+
+    return out;
+  }
+
+  dynamic match([dynamic m]) {
+    final struct = utility.struct;
+    final featureHook = utility.featureHook;
+
+    if (null != m) {
+      matchVal = struct.clone(m);
+      featureHook(entctx, 'SetMatch');
+    }
+
+    featureHook(entctx, 'GetMatch');
+    final out = struct.clone(matchVal);
+
+    return out;
+  }
+
+  // Streaming operation. Runs `action` through the full pipeline and returns
+  // a Stream over the result items, so the `streaming` feature's incremental
+  // output is reachable from a generated entity (a normal op call
+  // materialises the whole result). `callopts` parameterises the call:
+  //   - inbound (download): yields items/chunks from the streaming feature
+  //     when active, else falls back to the materialised items;
+  //   - outbound (upload): an async-iterable/Stream `body` is attached to the
+  //     request so the transport can stream a request payload;
+  //   - `ctrl` (pipeline control) and `signal` (cancellation) are honoured.
+  Stream<dynamic> stream(String action,
+      [dynamic args, dynamic callopts]) async* {
+    final utility = this.utility;
+
+    final makeContext = utility.makeContext;
+    final done = utility.done;
+    final featureHook = utility.featureHook;
+    final makePoint = utility.makePoint;
+    final makeSpec = utility.makeSpec;
+    final makeRequest = utility.makeRequest;
+    final makeResponse = utility.makeResponse;
+    final makeResult = utility.makeResult;
+
+    callopts = callopts ?? {};
+    final signal = callopts is Map ? callopts['signal'] : null;
+
+    final ctrl = <String, dynamic>{};
+    if (callopts is Map && callopts['ctrl'] is Map) {
+      (callopts['ctrl'] as Map).forEach((k, v) => ctrl[k.toString()] = v);
+    }
+    ctrl['stream'] = callopts;
+
+    final ctxmap = <String, dynamic>{
+      'opname': action,
+      'ctrl': ctrl,
+      'match': matchVal,
+      'data': dataVal,
+    };
+    if (args is Map) {
+      args.forEach((k, v) => ctxmap[k.toString()] = v);
+    }
+
+    final ctx = makeContext(ctxmap, entctx);
+
+    // Outbound: expose the caller's async-iterable/Stream payload so the
+    // request builder / transport can stream it as the request body.
+    final body = callopts is Map ? callopts['body'] : null;
+    if (null != body) {
+      final rd = ctx.reqdata is Map
+          ? Map<String, dynamic>.from(ctx.reqdata)
+          : <String, dynamic>{};
+      rd[r'body$'] = body;
+      ctx.reqdata = rd;
+      ctrl['stream_out'] = body;
+    }
+
+    dynamic fres;
+
+    try {
+      fres = featureHook(ctx, 'PrePoint');
+      if (fres is Future) {
+        await fres;
+      }
+      ctx.out['point'] = makePoint(ctx);
+      if (iserr(ctx.out['point'])) {
+        throw ctx.out['point'];
+      }
+
+      fres = featureHook(ctx, 'PreSpec');
+      if (fres is Future) {
+        await fres;
+      }
+      ctx.out['spec'] = makeSpec(ctx);
+      if (iserr(ctx.out['spec'])) {
+        throw ctx.out['spec'];
+      }
+
+      fres = featureHook(ctx, 'PreRequest');
+      if (fres is Future) {
+        await fres;
+      }
+      ctx.out['request'] = await makeRequest(ctx);
+      if (iserr(ctx.out['request'])) {
+        throw ctx.out['request'];
+      }
+
+      fres = featureHook(ctx, 'PreResponse');
+      if (fres is Future) {
+        await fres;
+      }
+      ctx.out['response'] = await makeResponse(ctx);
+      if (iserr(ctx.out['response'])) {
+        throw ctx.out['response'];
+      }
+
+      fres = featureHook(ctx, 'PreResult');
+      if (fres is Future) {
+        await fres;
+      }
+      ctx.out['result'] = makeResult(ctx);
+      if (iserr(ctx.out['result'])) {
+        throw ctx.out['result'];
+      }
+
+      fres = featureHook(ctx, 'PreDone');
+      if (fres is Future) {
+        await fres;
+      }
+
+      final result = ctx.result;
+
+      // Inbound: prefer the streaming feature's incremental Stream; else fall
+      // back to the materialised items so `stream` always yields.
+      if (null != result && result.stream is Function) {
+        await for (final item in result.stream()) {
+          if (_streamAborted(signal)) {
+            return;
+          }
+          yield item;
+        }
+      } else {
+        final data = done(ctx);
+        final items = data is List ? data : (null == data ? [] : [data]);
+        for (final item in items) {
+          if (_streamAborted(signal)) {
+            return;
+          }
+          yield item;
+        }
+      }
+    } catch (err) {
+      final uerr = unexpected(ctx, err);
+      if (null != uerr) {
+        throw uerr;
+      }
+    }
+  }
+
+  bool _streamAborted(dynamic signal) {
+    if (null == signal) {
+      return false;
+    }
+    if (signal is Map) {
+      return true == signal['aborted'];
+    }
+    try {
+      return true == (signal as dynamic).aborted;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  Map<String, dynamic> toJSON() {
+    final struct = utility.struct;
+    final out = <String, dynamic>{};
+    final d = struct.getdef(dataVal, {});
+    if (d is Map) {
+      d.forEach((k, v) => out[k.toString()] = v);
+    }
+  // The marker is NAMESPACED. It used to be `entity$` — a short, generic
+  // name, and the `$`-suffix convention is not unique to sdkgen. Seneca uses
+  // `entity$` on its own entities to hold the canon, so an SDK record fed
+  // into `entize` silently overwrote it and produced entities claiming a
+  // canon that does not exist: no error, just wrong entities.
+    out[r'voxgig$entity'] = Name;
+    return out;
+  }
+
+  @override
+  String toString() {
+    return Name + ' ' + utility.struct.jsonify(dataVal);
+  }
+
+  dynamic unexpected(dynamic ctx, dynamic err) {
+    final clean = utility.clean;
+    final struct = utility.struct;
+    final delprop = struct.delprop;
+
+    final ctrl = ctx.ctrl;
+
+    ctrl['err'] = err;
+
+    if (null != ctrl['explain']) {
+      ctx.ctrl['explain'] = clean(ctx, ctx.ctrl['explain']);
+      delprop(ctx.ctrl['explain']['result'], 'err');
+
+      if (null != ctx.result && null != ctx.result.err) {
+        ctrl['explain']['err'] = clean(ctx, {
+          'code': errcode(ctx.result.err),
+          'message': errmsg(ctx.result.err),
+        });
+      }
+
+      final cleanerr = clean(ctx, {
+        'code': errcode(err),
+        'message': errmsg(err),
+      });
+
+      if (null == ctrl['explain']['err']) {
+        ctrl['explain']['err'] = cleanerr;
+      } else if (ctrl['explain']['err']['message'] != cleanerr['message']) {
+        ctrl['explain']['unexpected'] = cleanerr;
+      }
+    }
+
+    if (false == ctrl['throw']) {
+      return null;
+    }
+
+    return err;
+  }
+}