@voxgig/sdkgen 4.8.3 → 4.10.0

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

@@ -1,177 +0,0 @@
-
-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/project/.sdk/src/cmp/dart/ReadmeExamplesTest_dart.ts

@@ -1,238 +0,0 @@
-
-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/project/.sdk/src/cmp/dart/ReadmeExplanation_dart.ts

@@ -1,53 +0,0 @@
-
-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/project/.sdk/src/cmp/dart/ReadmeHowto_dart.ts

@@ -1,152 +0,0 @@
-
-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/project/.sdk/src/cmp/dart/ReadmeInstall_dart.ts

@@ -1,59 +0,0 @@
-
-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
-}