@voxgig/sdkgen-langpack 0.0.1

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

@@ -0,0 +1,177 @@
+
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Type names come from the shared canonToType 'dart' column (single source of truth).
+
+// A type-correct Dart literal for a field's canonical type. Strings render
+// the quoted placeholder (single-quoted, matching the generated Dart style).
+function dartLit(type: any, placeholder: string = 'example'): string {
+  const k = canonScalarKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '<dynamic>[]'
+  if ('OBJECT' === k) return '<String, dynamic>{}'
+  return `'${placeholder}'`
+}
+
+
+// Op method spellings + descriptions (language-agnostic wording).
+// A `list()` on a NESTED entity needs its parent path params. The
+// quickstart used to emit `client.Moon().list()` for an entity at
+// `/planet/{planet_id}/moon`, which 404s against a live server from a
+// half-built URL — indistinguishable from "no such record". The model
+// already marks those params `reqd: true`; matchArg renders exactly them.
+function listMatchArg(ent: any): string {
+  const idF = entityIdField(ent)
+  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    const eVar = exampleVarName(entity.name, 'dart')
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`final ${eVar} = client.${entity.Name}();\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{${loadItems.map((it: any) =>
+          `'${it.name}': ${dartLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}}`
+        : ''
+      Content(`#### Example: Load
+
+\`\`\`dart
+final ${eVar} = await client.${entity.Name}().load(${loadArg});
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`dart
+final ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)});
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`dart
+final ${eVar} = await client.${entity.Name}().create({
+`)
+      createItems.map((it: any) => {
+        Content(`  '${it.name}': ${dartLit(it.type, 'example_' + it.name)},  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`});
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

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

@@ -0,0 +1,238 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+// Emits dart/test/readme_examples_test.dart — a COMPLETENESS + PRESENCE gate
+// over every ```dart fenced block in the three documents that ship dart
+// examples:
+//   - the repository ROOT README.md (one directory above the dart/ package),
+//   - the per-language dart/README.md,
+//   - the per-language dart/REFERENCE.md.
+//
+// Unlike the interpreted-language gates (py/rb), which EXECUTE every runnable
+// block in a subprocess, and the go gate, which COMPILES every block, this
+// gate is a dependency-free STRUCTURAL gate that runs inside the dependency-
+// free dart test harness (no `dart analyze`/`dart run` subprocess, so it never
+// depends on a resolvable package_config at test time). Per document it:
+//   1. extracts every ```dart fenced block (tagged by source doc + index);
+//   2. classifies each block into exactly one of
+//      {runnable, illustration, compiled-nonrunnable} and asserts the
+//      partition is complete (total == runnable + illustration + compiled);
+//   3. asserts PRESENCE: every available doc carries at least one dart block,
+//      and at least one RUNNABLE block (one that constructs the SDK or drives
+//      a `client`), so no doc silently ships zero exercised dart examples.
+//
+// A missing doc is SKIPPED (not failed) — the root README is optional in a
+// single-language checkout. The dart source is written with the fence marker
+// and newline built from escapes (` = backtick) so this template literal
+// stays clean.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const Name = model.const.Name
+  const sdkClass = Name + 'SDK'
+
+  // The API's capitalised semantic entities — used to detect entity-factory
+  // references (client.<Entity>() ) inside a block.
+  const entities = Object.values(getModelPath(model, `main.${KIT}.entity`) || {})
+    .filter((e: any) => e && e.active !== false)
+    .map((e: any) => nom(e, 'Name'))
+  const entitiesLiteral = 0 === entities.length
+    ? '<String>[]'
+    : "<String>['" + entities.join("', '") + "']"
+
+  File({ name: 'readme_examples_test.' + target.ext }, () => {
+    Content(`// ${Name} SDK — documentation dart-examples presence & completeness gate.
+// GENERATED — do not edit.
+//
+// A structural completeness gate over every dart fenced code block in three
+// documents:
+//   - the repository ROOT README.md (one directory above the dart/ package),
+//   - the per-language dart/README.md,
+//   - the per-language dart/REFERENCE.md.
+//
+// For each available document it partitions every block into exactly one of
+// {runnable, illustration, compiled-nonrunnable}, asserts the partition adds
+// up, and asserts the doc carries at least one runnable dart example. A
+// missing document is skipped, not failed.
+
+import 'dart:io';
+
+import 'harness.dart';
+import 'utility.dart';
+
+// The triple-backtick markdown code fence (\\u0060 == backtick) and newline,
+// built from escapes so the generator template literal stays clean.
+const String _fence = '\\u0060\\u0060\\u0060';
+const String _nl = '\\n';
+
+const String _sdkClass = '${sdkClass}';
+
+// The API's capitalised semantic entities, used to spot a client.<Entity>()
+// factory call inside a block.
+const List<String> _entities = ${entitiesLiteral};
+
+// The three documents held to the gate, tagged by human label and path
+// (relative to the package root, which is the CWD for 'dart run test/...').
+final List<List<String>> _docs = [
+  ['root README', '../README.md'],
+  ['dart README.md', 'README.md'],
+  ['dart REFERENCE.md', 'REFERENCE.md'],
+];
+
+// Split the doc on the code fence: odd-indexed segments are the inside of a
+// fenced block (an info string on the first line, then the code). Only fences
+// whose info string is exactly 'dart' are returned, so signature/markdown
+// tables and other-language fences are skipped.
+List<String> _blocksIn(String text) {
+  final parts = text.split(_fence);
+  final blocks = <String>[];
+  for (var i = 1; i < parts.length; i += 2) {
+    final seg = parts[i];
+    final lines = seg.split(_nl);
+    final info = lines[0].trim();
+    if ('dart' == info) {
+      blocks.add(lines.sublist(1).join(_nl));
+    }
+  }
+  return blocks;
+}
+
+// A block is RUNNABLE — and therefore MUST be exercised — when it constructs
+// the SDK (mentions the class) or drives a client the narrative built.
+bool _isRunnable(String block) {
+  if (block.contains(_sdkClass)) {
+    return true;
+  }
+  if (block.contains('client.')) {
+    return true;
+  }
+  for (final ent in _entities) {
+    if (block.contains('.' + ent + '(')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// A NARROW illustration: a non-runnable block whose every non-blank line is a
+// comment or an import — a pure signature/structure snippet with nothing to
+// run. Anything with real statements falls to the compiled-nonrunnable bucket.
+bool _isIllustration(String block) {
+  if (_isRunnable(block)) {
+    return false;
+  }
+  var sawLine = false;
+  for (final raw in block.split(_nl)) {
+    final line = raw.trim();
+    if ('' == line) {
+      continue;
+    }
+    sawLine = true;
+    if (line.startsWith('//')) {
+      continue;
+    }
+    if (line.startsWith('import ') || line.startsWith('export ')) {
+      continue;
+    }
+    return false;
+  }
+  return sawLine;
+}
+
+String _classify(String block) {
+  if (_isRunnable(block)) {
+    return 'runnable';
+  }
+  if (_isIllustration(block)) {
+    return 'illustration';
+  }
+  return 'compiled';
+}
+
+Map<String, int> _gate(String label, List<String> blocks) {
+  var runnable = 0;
+  var illustration = 0;
+  var compiled = 0;
+  for (final block in blocks) {
+    final kind = _classify(block);
+    if ('runnable' == kind) {
+      runnable++;
+    } else if ('illustration' == kind) {
+      illustration++;
+    } else {
+      compiled++;
+    }
+  }
+  final total = blocks.length;
+  print(_nl +
+      '[readme-examples] ' +
+      label +
+      ' dart blocks: total=' +
+      total.toString() +
+      ' runnable=' +
+      runnable.toString() +
+      ' compiled=' +
+      compiled.toString() +
+      ' illustration=' +
+      illustration.toString());
+
+  // Every block is accounted for by exactly one bucket.
+  ok(total == runnable + illustration + compiled,
+      label +
+          ': dart-block accounting does not add up — total=' +
+          total.toString() +
+          ' but runnable+compiled+illustration=' +
+          (runnable + illustration + compiled).toString());
+
+  return {
+    'total': total,
+    'runnable': runnable,
+    'compiled': compiled,
+    'illustration': illustration,
+  };
+}
+
+void tests() {
+  describe('ReadmeExamples', () {
+    for (final doc in _docs) {
+      final label = doc[0];
+      final rel = doc[1];
+
+      test('dart-examples: ' + label, (t) async {
+        final path = resolveTestPath(rel);
+        if (!File(path).existsSync()) {
+          t.skip(label + ' not found: ' + path);
+          return;
+        }
+
+        final text = File(path).readAsStringSync();
+        final blocks = _blocksIn(text);
+
+        ok(0 < blocks.length,
+            'expected at least one dart block in ' + label);
+
+        final stats = _gate(label, blocks);
+
+        ok(0 < (stats['runnable'] ?? 0),
+            'expected at least one runnable dart block in ' +
+                label +
+                ' (a block that constructs the SDK or drives a client)');
+      });
+    }
+  });
+}
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -0,0 +1,53 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import { dartPackageName } from './Package_dart'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const Name = model.const.Name
+  const pkg = dartPackageName(model)
+
+  Content(`### Maps in, typed models alongside
+
+The Dart SDK passes plain \`Map<String, dynamic>\` values through the
+operation pipeline rather than requiring typed objects at every call. This
+mirrors the dynamic nature of the API and keeps calls terse — a create is
+just \`create({'name': 'example'})\`.
+
+For a typed, documented view of each entity and operation, the generated
+\`${Name}Types.dart\` provides a class per entity plus per-op request/match
+classes (e.g. \`${Name}.fromMap(entity.data())\` and \`model.toMap()\`), so you
+can convert to and from those maps wherever you want compile-time structure.
+
+### Package structure
+
+\`\`\`
+${target.name}/
+├── lib/
+│   ├── ${Name}SDK.dart          -- Main SDK library (exported entry point)
+│   ├── ${Name}Types.dart        -- Typed entity + request/match models
+│   ├── ${Name}EntityBase.dart   -- Base class for entities
+│   ├── ${Name}Error.dart        -- SDK error type
+│   ├── Config.dart              -- Configuration
+│   ├── entity/                  -- Entity implementations
+│   ├── feature/                 -- Built-in features (base, test, log, ...)
+│   └── utility/                 -- Utility functions and vendored struct library
+└── test/                        -- Test suites (dart run test/main.dart)
+\`\`\`
+
+The main library (\`${Name}SDK.dart\`) re-exports the SDK class, the typed
+models, and every entity class, so a single
+\`import 'package:${pkg}/${Name}SDK.dart';\`
+brings in everything you need.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,152 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+// A type-correct Dart literal for a field's canonical type.
+function dartLit(type: any): string {
+  const k = canonScalarKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '<dynamic>[]'
+  if ('OBJECT' === k) return '<String, dynamic>{}'
+  return "'example'"
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity. primaryOp is null only when NO entity
+  // exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  const eVar = exampleVarName(eName.toLowerCase(), 'dart')
+  // Model-driven id key: null when the entity has no id-like field.
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = ''
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `{'${idF}': 'test01'}` : ''
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => it.name !== idF && it.name !== 'id')
+    const required = items.filter((it: any) => !it.optional)
+    const chosen = required.length ? required : items.slice(0, 3)
+    testArg = `{${chosen.map((it: any) => `'${it.name}': ${dartLit(it.type)}`).join(', ')}}`
+  }
+
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
+  const testModeExample = primaryOp
+    ? `// Entity ops return the ENTITY and throws on error;
+// call data() for the record.
+final ${eVar} = await client.${eName}().${primaryOp}(${testArg});
+// ${eVar} contains the mock response record
+print(${eVar});`
+    : `final result = await client.direct({'path': '/api/resource', 'method': 'GET'});
+print(result);`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\nexport ${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`dart
+final result = await client.direct({
+  'path': '/api/resource/{id}',
+  'method': 'GET',
+  'params': {'id': 'example'},
+});
+
+if (true == result['ok']) {
+  print(result['status']);  // 200
+  print(result['data']);    // response body
+} else {
+  // A non-2xx response carries status + data (the error body); a
+  // transport-level failure carries err instead. direct() never throws —
+  // branch on result['ok'].
+  print(result['status']);
+  print(result['err']);
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`dart
+// prepare() returns the fetch definition (or an error value on failure).
+final fetchdef = await client.prepare({
+  'path': '/api/resource/{id}',
+  'method': 'DELETE',
+  'params': {'id': 'example'},
+});
+
+print(fetchdef['url']);
+print(fetchdef['method']);
+print(fetchdef['headers']);
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`dart
+final client = ${model.const.Name}SDK.test();
+
+${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`dart
+Future<dynamic> mockFetch(dynamic url, dynamic init) async {
+  return {
+    'status': 200,
+    'statusText': 'OK',
+    'headers': <String, dynamic>{},
+    'json': () => {'id': 'mock01'},
+  };
+}
+
+final client = ${model.const.Name}SDK({
+  'base': 'http://localhost:8080',
+  'system': {
+    'fetch': mockFetch,
+  },
+});
+\`\`\`
+
+### Run live tests
+
+Set the live-mode environment variables:
+
+\`\`\`bash
+export ${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd ${target.name} && dart run test/main.dart
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -0,0 +1,59 @@
+
+import { cmp, Content, isPublished, repoInfo, packageVersion } from '@voxgig/sdkgen'
+
+import { dartPackageName } from './Package_dart'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const pkg = dartPackageName(model)
+
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+dart pub add ${pkg}
+\`\`\`
+
+Or add it to your \`pubspec.yaml\`:
+
+\`\`\`yaml
+dependencies:
+  ${pkg}: ^${packageVersion(model, target.name)}
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: not yet on pub.dev. Depend on it via the git release
+  // tag, or from a local path checkout.
+  const { repoUrl, releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to pub.dev. Add it as a git
+dependency (pinned to a release tag \`${target.name}/vX.Y.Z\`, see
+[Releases](${releasesUrl})) in your \`pubspec.yaml\`:
+
+\`\`\`yaml
+dependencies:
+  ${pkg}:
+    git:
+      url: ${repoUrl}
+      path: ${target.name}
+      ref: ${target.name}/v${packageVersion(model, target.name)}
+\`\`\`
+
+Or depend on a local source checkout:
+
+\`\`\`yaml
+dependencies:
+  ${pkg}:
+    path: ../${target.name}
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}