@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.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/project/.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/project/.sdk/src/cmp/dart/ReadmeHowto_dart.ts

@@ -0,0 +1,151 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, 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 = canonKey(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 bare record and throw on error.
+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

@@ -0,0 +1,59 @@
+
+import { cmp, Content, isPublished, repoInfo } 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}: ^0.0.1
+\`\`\`
+
+`)
+    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}/v0.0.1
+\`\`\`
+
+Or depend on a local source checkout:
+
+\`\`\`yaml
+dependencies:
+  ${pkg}:
+    path: ../${target.name}
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

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

@@ -0,0 +1,65 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client following idiomatic Dart conventions.
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`client.${nom(exampleEntity, 'Name')}()\` — each`
+    : 'each'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, which
+keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}