@voxgig/sdkgen-langpack 0.0.1

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

@@ -0,0 +1,207 @@
+
+// Typed-model generator (Dart target). Port of EntityTypes_ts.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file,
+// lib/<Sdk>Types.dart, with a Dart class per active entity plus a
+// request/match class per active op. Field/param sentinels ($STRING,
+// $INTEGER, ...) map to Dart types via the SHARED canonToType 'dart' column
+// (the single source of truth per language — do not keep a local table
+// here); the doc-comment sentinel key comes from the shared canonKey helper
+// so the source of truth (@voxgig/apidef VALID_CANON) is respected.
+//
+// TYPE CHOICE: plain classes with nullable fields + fromMap/toMap. The
+// generated ops accept/return runtime maps (Dart has no structural typing),
+// so these classes are the documented, convertible view of those maps —
+// mirroring the Python target's TypedDict approach at the level Dart
+// allows. Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch.
+
+import {
+  cmp, each, names,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonKey, canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions, deriveEntityNames } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'dart'
+
+
+// Dart reserved words that cannot be used as field names.
+const DART_KEYWORDS = new Set([
+  'assert', 'break', 'case', 'catch', 'class', 'const', 'continue',
+  'default', 'do', 'else', 'enum', 'extends', 'false', 'final', 'finally',
+  'for', 'if', 'in', 'is', 'new', 'null', 'rethrow', 'return', 'super',
+  'switch', 'this', 'throw', 'true', 'try', 'var', 'void', 'while', 'with',
+])
+
+
+// A name usable as a Dart field (valid identifier, not a keyword, public).
+function dartIdent(name: string): boolean {
+  return /^[A-Za-z][A-Za-z0-9_]*$/.test(name) && !DART_KEYWORDS.has(name)
+}
+
+
+// Emit a Dart data class from a list of {name, type, optional} items. All
+// fields are nullable (`optional` is documented) since the runtime passes
+// partial maps; fromMap is lenient (mismatched value types become null). An
+// item whose name is not a legal identifier is skipped (WITH a warning — the
+// key stays reachable via the runtime map, but its absence from the typed
+// model should be visible, not silent).
+function emitClass(typeName: string, items: any[], log?: any): void {
+  const usable = items.filter((it: any) => it && null != it.name && dartIdent(it.name))
+
+  items.forEach((it: any) => {
+    if (it && null != it.name && !dartIdent(it.name) && log && log.warn) {
+      log.warn({
+        point: 'entity-types-skip-field', typeName, field: it.name,
+        note: `dart: field "${it.name}" of ${typeName} has no legal Dart ` +
+          `identifier form; omitted from the typed model (still reachable ` +
+          `via the runtime map)`,
+      })
+    }
+  })
+
+  Content(`class ${typeName} {
+`)
+  usable.forEach((it: any) => {
+    const base = canonToType(it.type, LANG)
+    const t = 'dynamic' === base ? 'dynamic' : base + '?'
+    const req = it.optional ? '' : ' (required at the API)'
+    Content(`  /// ${canonKey(it.type) || 'ANY'}${req}
+  ${t} ${it.name};
+`)
+  })
+
+  if (0 === usable.length) {
+    Content(`  ${typeName}();
+
+  factory ${typeName}.fromMap(Map<String, dynamic> m) => ${typeName}();
+
+  Map<String, dynamic> toMap() => <String, dynamic>{};
+`)
+  }
+  else {
+    Content(`
+  ${typeName}({
+`)
+    usable.forEach((it: any) => {
+      Content(`    this.${it.name},
+`)
+    })
+    Content(`  });
+
+  factory ${typeName}.fromMap(Map<String, dynamic> m) => ${typeName}(
+`)
+    usable.forEach((it: any) => {
+      const base = canonToType(it.type, LANG)
+      if ('dynamic' === base) {
+        Content(`        ${it.name}: m['${it.name}'],
+`)
+      }
+      else {
+        Content(`        ${it.name}: m['${it.name}'] is ${base} ? m['${it.name}'] : null,
+`)
+      }
+    })
+    Content(`      );
+
+  Map<String, dynamic> toMap() {
+    final m = <String, dynamic>{};
+`)
+    usable.forEach((it: any) => {
+      Content(`    if (null != ${it.name}) {
+      m['${it.name}'] = ${it.name};
+    }
+`)
+    })
+    Content(`    return m;
+  }
+`)
+  }
+
+  Content(`}
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+  const { target } = props
+
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = deriveEntityNames(entity)
+  // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
+  // entity not yet named (e.g. a fieldless placeholder) would otherwise read
+  // `Name = undefined` below. Parity with the go emitter's fix.
+
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
+  File({ name: model.const.Name + 'Types.' + target.ext }, () => {
+
+    Content(`// Typed models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels (source of truth: @voxgig/apidef VALID_CANON).
+// Do not edit by hand.
+//
+// The operation pipeline passes plain maps; these classes are the typed,
+// convertible view: \`${model.const.Name}.fromMap(ent.data())\` / \`model.toMap()\`.
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one field per model field, `req:false` -> optional.
+      emitClass(Name, fields.map((f: any) => ({
+        name: f.name,
+        type: f.type,
+        optional: false === f.req,
+      })), log)
+
+      // Per active op: a request/match type. The members and each member's
+      // required/optional decision come from the shared partiality policy
+      // (opRequestShape); this file only renders them as a Dart class.
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        emitClass(typeName, items, log)
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

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

@@ -0,0 +1,87 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, camelify, names,
+  Content, File, Folder, Fragment,
+  entityClassName, entityCollection,
+} from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+import { EntityOperation } from './EntityOperation_dart'
+
+
+const Entity = cmp(function Entity(props: any) {
+  const { model, stdrep } = props.ctx$
+  const { target, entity } = props
+
+  // Collision-free entity CLASS name (see entityClassName): normally
+  // `<Name>Entity`, disambiguated when it would clash with another entity's
+  // data-type name. The class file name and the Main accessor both use
+  // this, so they always agree.
+  const entityColl = entityCollection(model)
+  const cls = entityClassName(entity, entityColl)
+
+  const entrep = {
+    ...stdrep,
+  }
+
+  names(entrep, entity.Name, 'EntityName')
+
+  const ff = Path.normalize(__dirname + '/../../../src/cmp/dart/fragment/')
+
+  Folder({ name: 'lib/entity' }, () => {
+
+    File({ name: cls + '.' + target.ext }, () => {
+
+      const opnames = Object.keys(entity.op || {})
+
+      const opfrags =
+        (['load', 'list', 'create', 'update', 'remove']
+          .reduce((a: any, opname: string) =>
+          (a['#' + camelify(opname) + 'Op'] =
+            !opnames.includes(opname) ? '' : ({ indent }: any) => {
+              EntityOperation({ ff, opname, indent, entity, entrep })
+            }, a), {}))
+
+      Fragment({
+        from: ff + 'Entity.fragment.dart',
+        replace: {
+          ...entrep,
+          entityname: entity.name,
+          SdkName: model.const.Name,
+          EntityName: entity.Name,
+
+          // Class token decoupled from the EntityName data-type token in
+          // Entity.fragment.dart so the class can be renamed independently.
+          EntyClass: cls,
+
+          '#TypeImports': ({ indent }: any) => Content({ indent },
+            `// Typed models: see ../${model.const.Name}Types.dart ` +
+            `(${entity.Name} and the per-op request/match types).`),
+
+          // dart:async (Future/Stream) and ErrUtility are only referenced by
+          // op method bodies, so an op-less entity would import them unused.
+          // Emit them only when the entity actually has operations.
+          '#OpImports': opnames.length > 0
+            ? ({ indent }: any) => Content({ indent },
+              `import 'dart:async';\nimport '../utility/ErrUtility.dart';`)
+            : '',
+
+          ...opfrags,
+        }
+      })
+
+    })
+  })
+})
+
+
+
+export {
+  Entity
+}

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

@@ -0,0 +1,34 @@
+
+import {
+  Content,
+  File,
+  cmp,
+} from '@voxgig/sdkgen'
+
+
+const Gitignore = cmp(async function Gitignore(_props: any) {
+  File({ name: '.gitignore' }, () => {
+    Content(`# Dart tooling
+.dart_tool/
+.packages
+build/
+*.dill
+
+# Library packages do not commit the lockfile
+pubspec.lock
+
+# Logs
+*.log
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+`)
+  })
+})
+
+
+export {
+  Gitignore
+}

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

@@ -0,0 +1,33 @@
+
+
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+
+const MainEntity = cmp(async function MainEntity(props: any) {
+  const { entity } = props
+  const { model } = props.ctx$
+
+  // Return the collision-free class TYPE (entityClassName); the accessor
+  // METHOD name (entity.Name) is unchanged so callers still write
+  // client.<Name>().
+  const cls = entityClassName(entity, entityCollection(model))
+
+  Content(`
+  // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({'id': ...})\`.
+  ${cls} ${entity.Name}([dynamic entopts]) {
+    return ${cls}(this, entopts);
+  }
+
+`)
+
+})
+
+
+export {
+  MainEntity
+}

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

@@ -0,0 +1,178 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each,
+  List, File, Content, Copy, Folder, Fragment, Line,
+  entityClassName, entityCollection, pluginExcludes, targetFeatures,
+  TEST_CONTROL_EXCLUDE
+} from '@voxgig/sdkgen'
+
+
+import type {
+  ModelEntity
+} from '@voxgig/apidef'
+
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+
+import { Package } from './Package_dart'
+import { Config } from './Config_dart'
+import { Gitignore } from './Gitignore_dart'
+import { MainEntity } from './MainEntity_dart'
+import { EntityBase } from './EntityBase_dart'
+import { EntityTypes } from './EntityTypes_dart'
+import { SdkError } from './SdkError_dart'
+
+
+const Main = cmp(async function Main(props: any) {
+
+  // Needs type: target object
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Gated by the applicability tags, so this target never emits a hook for
+  // a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
+
+  // Does the secrets feature apply here and is it switched on? Both, since
+  // targetFeatures already dropped it for a target with no sekreto port.
+  const secrets = null != feature.secrets
+
+  Package({ target })
+
+  Gitignore({})
+
+  // Copy tm/dart files with replacements. The src/feature/* dirs exist only
+  // for the feature-add copy mechanism (real feature sources live under
+  // lib/feature/), so they are excluded from the generated package.
+  Copy({
+    from: 'tm/' + target.name,
+    // pluginExcludes: the generate-time plugin trim (an INACTIVE plugin
+    // group's declared files stay out of the tree - the model's `path`
+    // entries are target-root-relative, which is this Copy's root). The
+    // FEATURE-level trim for dart stays an add-time concern (vendor-tag
+    // rollout, Decision 5), exactly as for go and py.
+    //
+    // It must be EXACT for dart in a way it need not be elsewhere:
+    // `dart analyze` walks the whole package, so a group `path` list that
+    // omits a file another vendored file imports is a hard build failure
+    // rather than a silent runtime miss.
+    //
+    // `^src/`, ANCHORED, and the anchor is load-bearing. CopyOp seeds its
+    // walk with an empty path, so an exclude names paths within the copied
+    // tree - and the unanchored `/src\//` this used to be matched ANY path
+    // with a `src/` segment. The vendored sekreto port keeps upstream's
+    // layout, which is `sekreto/src/*.dart`, so the whole secrets core was
+    // silently dropped from the generated package while the plugins beside
+    // it survived: nine undefined-symbol errors from `dart analyze` and no
+    // clue in the copy that anything had been excluded.
+    exclude: [/^src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
+  Folder({ name: 'lib' }, () => {
+
+    SdkError({ target })
+
+    File({ name: model.const.Name + 'SDK.' + target.ext }, () => {
+
+      Line(`// ${model.const.Name} ${target.Name} SDK`)
+      Line(``)
+
+      List({ item: entity }, ({ item }: any) => {
+        const cls = entityClassName(item, entityCollection(model))
+        return Line(`import 'entity/${cls}.dart';`)
+      })
+
+      // Re-export the generated typed models and entity classes so
+      // consumers can import everything from '<Sdk>SDK.dart'.
+      Line(``)
+      Line(`export '${model.const.Name}Types.dart';`)
+      List({ item: entity }, ({ item }: any) => {
+        const cls = entityClassName(item, entityCollection(model))
+        return Line(`export 'entity/${cls}.dart';`)
+      })
+
+      Fragment(
+        {
+          from: Path.normalize(__dirname + '/../../../src/cmp/dart/fragment/Main.fragment.dart'),
+          replace: {
+            ...props.ctx$.stdrep,
+
+            // SECRETS. Emitted only when the feature applies to this target
+            // AND the model activates it. An unconditional edit here would
+            // land in every generated SDK and break the inactive-output
+            // gate: a model without the feature must generate exactly as it
+            // did before the migration.
+            //
+            // The accessor finds the feature BY NAME in the public
+            // `features` list rather than through a planted `_secrets`
+            // field, which is what ts and js use: a leading underscore is
+            // LIBRARY-private in Dart, so a feature in its own library
+            // cannot write one on the SDK at all (see the note in
+            // SecretsFeature.dart).
+            //
+            // The LIVE Sekreto, never a clone: it holds provider and cache
+            // state, so a copy would resolve into something the transport
+            // never sees.
+            // Indentation is baked into the string, and the marker sits at
+            // column 0 in the fragment: jostraca hands the marker's own
+            // indent to the handler but does not re-indent a multi-line
+            // Content, so an indented marker emitted an unindented method
+            // body AND left the indent behind as trailing whitespace when
+            // the slot was empty. At column 0 an inactive SDK gains one
+            // blank line and nothing else.
+            '// #SecretsAccessor': () => secrets ?
+              Content(`
+  // The live sekreto chain this SDK resolves its credential through, for
+  // callers who want arbitrary secrets or redaction:
+  //
+  //   await sdk.secrets().get('db.password')
+  //   sdk.secrets().redact(logline)
+  //
+  // Null before the secrets feature has initialised, and in an SDK where
+  // it is switched off.
+  dynamic secrets() {
+    for (final f in features) {
+      if ('secrets' == f.name) {
+        return f.sekreto();
+      }
+    }
+    return null;
+  }
+
+`) : undefined,
+          }
+        },
+
+        // Entities
+        () => {
+          each(entity, (entity: ModelEntity) => {
+            const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
+            const entprops = { target, entity, entitySDK }
+            MainEntity(entprops)
+          })
+        })
+    })
+
+    Config({ target })
+    EntityBase({ target })
+    EntityTypes({ target })
+
+  })
+})
+
+
+export {
+  Main
+}

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

@@ -0,0 +1,82 @@
+
+import {
+  Content,
+  File,
+  cmp,
+  collectDeps,
+  pkgDescription,
+  keywords,
+  repoInfo,
+  packageVersion,
+} from '@voxgig/sdkgen'
+
+
+import type {
+  Model,
+} from '@voxgig/apidef'
+
+
+// pub.dev package names must be lowercase identifiers ([a-z0-9_], starting
+// with a letter). The import path (`lib/`) is unaffected.
+function dartPackageName(model: any): string {
+  let name = `${model.name}_sdk`.toLowerCase().replace(/[^a-z0-9_]/g, '_')
+  if (!/^[a-z]/.test(name)) {
+    name = 'sdk_' + name
+  }
+  return name
+}
+
+
+const Package = cmp(async function Package(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const { repoUrl, issuesUrl } = repoInfo(model)
+  const kw = keywords(model)
+
+  File({ name: 'pubspec.yaml' }, () => {
+    Content(`name: ${dartPackageName(model)}
+description: >-
+  ${pkgDescription(model, target.name)}
+version: ${packageVersion(model, target.name)}
+homepage: ${repoUrl}
+repository: ${repoUrl}
+issue_tracker: ${issuesUrl}
+topics:
+`)
+
+    // pub.dev topics: max 5, lowercase, hyphenated.
+    kw.slice(0, 5).forEach((k: string) => {
+      Content(`  - ${String(k).toLowerCase().replace(/[^a-z0-9-]/g, '-')}
+`)
+    })
+
+    Content(`environment:
+  sdk: '>=3.0.0 <4.0.0'
+`)
+
+    // Runtime is dependency-free (dart:io + dart:convert + vendored struct);
+    // target/feature deps, when declared, land here.
+    const deps: Record<string, string> = {}
+    for (const d of collectDeps(model, target.name, target.deps, ctx$.log)) {
+      deps[d.name] = d.source === 'target' ? (d.version || 'any') : d.version
+    }
+
+    if (0 < Object.keys(deps).length) {
+      Content(`dependencies:
+`)
+      for (const [name, version] of Object.entries(deps)) {
+        Content(`  ${name}: '${version}'
+`)
+      }
+    }
+  })
+})
+
+
+export {
+  Package,
+  dartPackageName,
+}