@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/src/cmp/php/Config_php.ts

@@ -35,45 +35,11 @@ import {
 } from './utility_php'
 
 
-// PLUGIN DEFINITION REQUIRES AND THE feature_plugins ACCESSOR (the php peer
-// of cmp/rb/Config_rb.ts's rbPlugins and cmp/py/Config_py.ts's
-// pluginImports/pluginDefs).
-//
-// Upstream sekreto replaced its self-registration registry with
-// voxgig/plugin definitions: a provider kind the caller did not pass in via
-// `plugins: [...]` is unknown to that Sekreto. So config names each active
-// plugin's exported DEFINITION FUNCTION (the model's `def.php` map) and
-// hands the list to the feature.
-//
-// A METHOD rather than a constant, and this is php's own constraint: a
-// plugin definition holds CLOSURES (sekreto's Providers.php says so where
-// it declares `builtins()`), and php has no constant that can. The
-// `require_once` calls live INSIDE the method for the same reason upstream
-// puts them inside plugins.php's own accessors - a plugin file is read only
-// when a feature actually asks for its definitions.
-//
-// The `def` map is declared in the model rather than derived from filenames
-// because one file may export several definitions (sekreto's aws.php
-// exports awssecrets AND awsparams) - hence the de-duplication by path, so
-// a two-definition file yields ONE require_once. A def value is the file's
-// path under tm/php, which is this target's root and also config.php's own
-// directory, so the require is that path verbatim.
-//
-// GATED, like rb: the whole block is emitted only when an active feature
-// DECLARES a plugin catalogue for this target. An SDK that does not carry
-// the secrets feature must be byte-identical to what it was before the
-// feature existed, and an unread accessor is not a thing a simple SDK
-// should have to explain. The feature reads it through `method_exists`, so
-// its absence is not a load error.
 function phpPlugins(model: any, feature: any) {
   const defs: Record<string, { paths: string[], syms: string[] }> = {}
   let declared = false
 
   each(feature, (f: any) => {
-    // `only_active: false`, and this is the whole subtlety: the feature
-    // object a component is handed has ALREADY been filtered, so asking it
-    // whether a catalogue EXISTS answers no as soon as every group is off.
-    // (Same trap helpers/featureSource documents one level down.)
     const all = getModelPath(model, `main.${KIT}.feature.${f.name}.plugin`,
       { required: false, only_active: false }) || {}
 
@@ -85,10 +51,6 @@ function phpPlugins(model: any, feature: any) {
     const syms: string[] = []
 
     each(f.plugin, (plugin: any) => {
-      // Filter on `active` HERE rather than trusting the feature object to
-      // arrive filtered: getting it wrong in this direction emits a
-      // require_once for a file the plugin trim just deleted - an SDK that
-      // does not load, rather than one that merely carries too much.
       if (false === plugin.active || null == plugin.active) return
 
       for (const [sym, one] of Object.entries(plugin.def?.php || {})) {
@@ -113,15 +75,11 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Gated by the applicability tags, so this target never imports or
-  // registers a feature it has no source for. One rule, one place:
-  // helpers/applicability.
   const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
   // `in` and `name` travel with the prefix now. They were resolved by
   // apidef all along and dropped here, so an apiKey-in-query API got an
@@ -134,9 +92,6 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // Templated server URL: emit the spec's server-variable defaults so the
-  // runtime can substitute {name} placeholders in base (see MakeOptions).
-  // `$` is escaped so a default can never open a PHP interpolation.
   const svars = serverVariables(model)
   const phps = (s: string) => JSON.stringify(s).replace(/\$/g, '\\$')
   const serverBlock = 0 === svars.length ? '' :
@@ -152,21 +107,12 @@ const Config = cmp(async function Config(props: any) {
                 ],\n`
     : ''
 
-  // The same config as an OBJECT, built by the shared helper so this target's
-  // literal and the data that replaces it above the threshold are the same
-  // config by construction. The JSON is what the threshold is measured on -
-  // emitted source size varies by language, the model does not. Passing the
-  // target name opts in to the main.slug/version/target identity fields -
-  // both representations below carry them, keeping the reps interchangeable.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
   const { defs: pluginDefs, declared: pluginDeclared } = phpPlugins(model, feature)
   const pluginFeatures = Object.keys(pluginDefs).sort()
 
-  // Emitted whenever a catalogue is declared, even with every group off:
-  // the feature asks for the list unconditionally, and an SDK whose chain
-  // is all built-ins still has to be answered with an empty one.
   const featurePluginsBlock = !pluginDeclared ? '' : `
     /**
      * The sekreto plugin DEFINITIONS the model selected per feature, from
@@ -224,25 +170,6 @@ class ${model.const.Name}Config
 
 `)
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // An array literal is compiled opcode by opcode and held in the opcache
-    // entry for this file; a string constant is one token, and `json_decode`
-    // (C) builds the array far faster than the equivalent literal.
-    //
-    // PHP cannot tell an empty list from an empty map, so `{}` and `[]` decode
-    // to the same value and the two representations have to AGREE about which
-    // one the literal would have produced. `formatPhpArray` emits `[]` for
-    // every empty map, and the literal branch hand-writes `(object)[]` in
-    // exactly two places - `entity` and `options.entity`, and only when the
-    // model declares no entities at all, because the SDK runtime validator
-    // wants a map there. This reproduces that rule rather than improving on
-    // it: an emission wart is not something the data path gets to fix
-    // unilaterally, or the two branches stop being interchangeable.
-    //
-    // A SINGLE-quoted literal, so the JSON survives verbatim: a double-quoted
-    // PHP string would interpolate any `$name` the model contains - and the
-    // model is full of them (`$STRING`, `$action`).
     if (asData) {
       Content(`    /**
      * THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
@@ -323,9 +250,6 @@ class ${model.const.Name}Config
 `)
     })
 
-    // PHP can't distinguish empty list from empty map; the SDK runtime
-    // validator wants an object for `entity` and `feature.test.entity`. Use
-    // `(object)[]` when the map is empty so the merge preserves map shape.
     const entityIsEmpty = Object.keys(entity || {}).length === 0
     if (entityIsEmpty) {
       Content(`            ],

package/project/.sdk/src/cmp/php/EntityTypes_php.ts

@@ -1,28 +1,5 @@
 
 
-// Typed-model generator (PHP target).
-//
-// Ported from the TypeScript reference EntityTypes_ts.ts. Reads
-// main.<KIT>.entity.<e>.fields[] and per-op params (op.<name>.points[].args.params[])
-// and emits one file, types/<Sdk>Types.php, containing a PHP 8 class with typed
-// properties per active entity plus a request/match class per active op. Field/param
-// sentinels ($STRING, $INTEGER, ...) are turned into real PHP types by the shared
-// sdkgen helper `canonToType` (source of truth: @voxgig/apidef VALID_CANON):
-//   $STRING -> string, $INTEGER -> int, $NUMBER -> float, $BOOLEAN -> bool,
-//   $OBJECT/$ARRAY -> array, unknown -> mixed.
-//
-// Type-name scheme (IDENTICAL to TS): data type = <Name>; per-op request
-// <Name>LoadMatch / <Name>ListMatch / <Name>RemoveMatch (query/id ops),
-// <Name>CreateData / <Name>UpdateData (body ops). An op WITH params -> a typed
-// class of those params (reqd:false -> nullable, defaulted null). An op WITHOUT
-// params -> a match class over the entity fields, all nullable/optional (the
-// PHP stand-in for TS `Partial<Name>`; callers may also pass a plain assoc-array).
-//
-// PHP has no generics and no structural typing, so these classes are documentation-
-// grade value objects: op signatures keep a permissive native type (assoc-array in,
-// mixed out at the item-5 boundary) and surface the class names via PHPDoc. The file
-// lands under types/ and is registered on composer's classmap autoload (see
-// Package_php.ts) so `new <Name>()` / type references resolve globally.
 
 import {
   cmp, each, names,
@@ -40,19 +17,11 @@ import {
 const LANG = 'php'
 
 
-// A valid PHP property/label name (identifiers only; the corpus never carries
-// exotic field names, but guard so a bad name can never emit invalid PHP).
 function validName(name: string): boolean {
   return /^[A-Za-z_\x80-\xff][A-Za-z0-9_\x80-\xff]*$/.test(name)
 }
 
 
-// Emit one typed PHP property line. `mixed` is already nullable in PHP and
-// rejects the `?` prefix, so it is special-cased; every other optional field
-// becomes `?type` with a `= null` default so the property is safely optional.
-// A `$NULL`-typed field maps to the 'null' type name, which is not usable as
-// a property type here (`?null` is a fatal, and standalone `null` needs
-// PHP >= 8.2), so it degrades to `mixed` too.
 function propLine(name: string, sentinel: unknown, optional: boolean): string {
   const type = canonToType(sentinel, LANG)
   if ('mixed' === type || 'null' === type) {
@@ -69,10 +38,6 @@ function propLine(name: string, sentinel: unknown, optional: boolean): string {
 const EntityTypes = cmp(function EntityTypes(props: any) {
   const { model, log } = props.ctx$
 
-  // 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
@@ -84,9 +49,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // 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)
 
   Folder({ name: 'types' }, () => {
@@ -114,18 +76,8 @@ declare(strict_types=1);
         const fields = (ent.fields ? each(ent.fields) : [])
           .filter((f: any) => f.active !== false && validName(f.name))
 
-        // PHP refuses a reserved word where a class name is expected, and the
-        // check is CASE-INSENSITIVE — an entity named `Namespace` emitted
-        // `class Namespace`, which does not parse, and took the whole types
-        // file with it (issue #64). phpSafeTypeName appends `Type` on a real
-        // collision and leaves every other name untouched.
-        //
-        // Only the bare data class needs it: the per-op names below already
-        // carry a suffix no reserved word matches, and the entity accessor is
-        // a method, which PHP resolves separately.
         const TypeName = phpSafeTypeName(Name)
 
-        // Entity data model: one typed property per field (`req:false` -> nullable).
         Content(`/** ${Name} entity data model. */
 class ${TypeName}
 {
@@ -137,9 +89,6 @@ class ${TypeName}
 
 `)
 
-        // Per active op: a request/match class. Members and their optionality
-        // come from the shared partiality policy (opRequestShape); this file
-        // only renders them as a PHP value-object class.
         const ops = ent.op || {}
         ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
           if (null == ops[opname]) {

package/project/.sdk/src/cmp/php/MainEntity_php.ts

@@ -19,12 +19,6 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   // (below) is unchanged so callers still write $client->${entity.Name}().
   const cls = entityClassName(entity, entityCollection(model))
 
-  // Canonical facade method name is the PascalCase entity Name
-  // (`$client->${entity.Name}()`). PHP method names are case-insensitive, so
-  // the lowercase spelling `$client->${entity.name}()` still resolves here as
-  // a convenience — we declare it ONCE under the PascalCase name. An entity
-  // literally named 'test' would collide (case-insensitively) with the static
-  // `test()` test-mode constructor, so mangle to `<Name>_` in that case.
   const accessor = phpEntityAccessor(entity.Name)
 
   // The backing field is mangled independently of the accessor: the two are

package/project/.sdk/src/cmp/php/Main_php.ts

@@ -23,6 +23,7 @@ import {
 
 import { Package } from './Package_php'
 import { Config } from './Config_php'
+import { Schema } from './Schema_php'
 import { PrepareAuth } from './PrepareAuth_php'
 import { Gitignore } from './Gitignore_php'
 import { MainEntity } from './MainEntity_php'
@@ -47,27 +48,12 @@ const Main = cmp(async function Main(props: any) {
   // Copy tm/php files with replacements
   Copy({
     from: 'tm/' + target.name,
-    // ANCHORED at the template root. Copy's exclude matches the
-    // SOURCE-RELATIVE path, so the old unanchored /src\// also pruned
-    // `feature/secrets/sekreto/src/` - the vendored sekreto core, whose
-    // directory depth is fixed by upstream and by the vendoring guard. The
-    // anchored form prunes the same top-level `tm/php/src/` placeholder
-    // tree (a `src` directory entry matches on the `$` arm, so the whole
-    // subtree is still pruned at the directory) and nothing else.
-    //
-    // 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). With
-    // no active feature declaring a plugin catalogue it is EMPTY, so a
-    // simple SDK's output is unchanged. The FEATURE-level trim for php
-    // stays an add-time concern (vendor-tag rollout, Decision 5).
     exclude: [/^src(\/|$)/, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }
   })
 
-  // Generate main SDK file
   File({ name: model.const.Name.toLowerCase() + '_sdk.' + target.ext }, () => {
 
     Fragment(
@@ -104,6 +90,7 @@ const Main = cmp(async function Main(props: any) {
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
   // GENERATED, NOT COPIED. Where the credential goes is a fact about the

package/project/.sdk/src/cmp/php/Package_php.ts

@@ -69,7 +69,7 @@ const Package = cmp(async function Package(props: any) {
   },
   "autoload": {
     "files": ["${model.const.Name.toLowerCase()}_sdk.php"],
-    "classmap": ["core/", "entity/", "feature/", "types/", "utility/", "config.php", "features.php"]
+    "classmap": ["core/", "entity/", "feature/", "types/", "utility/", "config.php", "schema.php", "features.php"]
   },
   "autoload-dev": {
     "classmap": ["test/"]

package/project/.sdk/src/cmp/php/PrepareAuth_php.ts

@@ -17,38 +17,10 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// This was a static file in `tm/php/utility/` that hardcoded an
-// `authorization` HEADER. apidef has always resolved the scheme's `in` and
-// `name` into `main.kit.info.security` — joplin's says
-// `in: "query", name: "token"` — and generation dropped both. The result
-// was an SDK that sent a header the API does not read and never sent the
-// query parameter it does, so it could not authenticate at all. Four repos
-// in the cedar fleet shipped that way: joplin (`token`), pipedrive
-// (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time.
-//
-// The php peer of cmp/ts/PrepareAuth_ts.ts.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  // FOLDER NESTING. Main_php opens NO folder around its children — it
-  // writes `<sdk>_sdk.php`, `features.php` and (inside `Folder('.')`)
-  // `config.php` straight into the target root, and each sibling component
-  // opens its own single level (EntityTypes -> `types/`, Entity ->
-  // `entity/`, Test -> `test/`). The template this replaces lived at
-  // `tm/php/utility/PrepareAuth.php` and the blanket Copy puts `tm/php/*`
-  // at the target root, so the generated file belongs at `utility/`, one
-  // folder deep. (This is NOT the ts layout: there Main already opens
-  // `src`, so PrepareAuth_ts must not open a second one.)
   Folder({ name: 'utility' }, () => {
     File({ name: 'PrepareAuth.' + target.ext }, () => {
       Content(render({
@@ -57,9 +29,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
         where: resolveAuthIn(model),
         name: resolveAuthName(model),
         basic: isHttpBasicAuth(model),
-        // Read so the resolution is exercised here too, even though the
-        // prefix is a RUNTIME option (`options.auth.prefix`, emitted by
-        // Config_php) rather than something baked into this file.
         prefix: resolveAuthPrefix(model),
       }))
     })
@@ -67,28 +36,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
 })
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
-// this first; same reasoning, same fix, and php's own lane proves it here).
-//
-// `isAuthActive` is false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
-// not a ban on ever sending a credential: apidef writes it for every spec
-// with no securitySchemes block, GitHub's official OpenAPI included, and
-// those SDKs are still expected to honour an `apikey` the caller passes.
-// The template placed the credential unconditionally, so they did.
-//
-// Gating the body on `isAuthActive` therefore does not trim dead code, it
-// deletes working authentication. MEASURED, not assumed: with the wider gate
-// this component emitted the no-op for generatedcompile's own fixture
-// (`main: kit: info: { ... auth: false }`) and the php lane went red —
-//
-//   php: auth null beats an explicit apikey
-//     FAIL: baseline broken: an ordinary apikey was not sent
-//
-// So the no-op is emitted only when the PROJECT says so:
-// `config.auth.active: false`, an explicit per-SDK switch nobody sets by
-// accident. A spec that is merely silent keeps the credential path it has
-// always had.
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -116,9 +63,6 @@ declare(strict_types=1);
 
 `
 
-  // AUTH SWITCHED OFF BY THE PROJECT (see authSwitchedOn for why only an
-  // EXPLICIT switch counts). The SDK gets a prepare_auth that is honest
-  // about it rather than one that deletes a header nobody set.
   if (!spec.active) {
     return head + `// This SDK is configured with authentication off, so there is no
 // credential to place. The class stays in the pipeline because make_spec
@@ -174,20 +118,12 @@ function bagVar(where: string): string {
 }
 
 
-// The constant holding the credential's NAME, per placement. `HEADER_AUTH`
-// keeps the name the template used, so a header SDK regenerates unchanged.
 function credConst(where: string): string {
   return 'query' === where ? 'QUERY_AUTH' : 'cookie' === where ? 'COOKIE_AUTH' : 'HEADER_AUTH'
 }
 
 
 function constants(spec: AuthSpec): string {
-  // A HEADER NAME GOES IN LOWERCASE, as every target's template has always
-  // written it (`authorization`): request header names are case-insensitive,
-  // and this SDK's own response headers are lowercased by the fetcher, so
-  // lowercasing here keeps one spelling throughout — and keeps the default
-  // byte-identical to the template this replaces. A query parameter and a
-  // cookie name are CASE-SENSITIVE, so those go in verbatim.
   const name = 'header' === spec.where ? spec.name.toLowerCase() : spec.name
 
   const cookieConst = 'cookie' === spec.where ?
@@ -203,8 +139,6 @@ ${secretConst}    private const NOT_FOUND = '__NOTFOUND__';
 }
 
 
-// The `options.auth` block is absent (`auth: null`) — drop any stale
-// credential the caller's own options put in the bag.
 function suppressed(where: string): string {
   if ('cookie' === where) {
     // NOTHING TO CLEAR. The cookie header may carry the caller's own
@@ -260,8 +194,6 @@ function placeBlock(spec: AuthSpec): string {
             || $apikey === null`
 
   if ('cookie' === spec.where) {
-    // A MISSING CREDENTIAL CLEARS NOTHING HERE, for the reason `suppressed`
-    // gives: the cookie header is shared with the caller's own cookies.
     return `
         $missing = ${missing};
 
@@ -309,8 +241,6 @@ function placeBlock(spec: AuthSpec): string {
 }
 
 
-// A PHP single-quoted string literal: only the backslash and the quote
-// itself need escaping, and single quotes never interpolate a `$name`.
 function phpstr(s: string): string {
   return "'" + String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'"
 }
@@ -318,8 +248,5 @@ function phpstr(s: string): string {
 
 export {
   PrepareAuth,
-  // Exported so the emitted PHP can be exercised directly (tests, and a
-  // one-line check of what a given placement renders) without standing up a
-  // full generation run.
   render,
 }

package/project/.sdk/src/cmp/php/ReadmeEntity_php.ts

@@ -54,7 +54,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   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)
 
     Content(`
@@ -108,9 +107,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     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, so
-      // the example always works.
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/php/ReadmeExamplesTest_php.ts

@@ -7,39 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits test/ReadmeExamplesTest.php — a PHPUnit COMPLETENESS GATE that
-// guarantees every fenced php code example in the package docs is unit-tested.
-// It reads ALL THREE docs — the root (multi-language) ../../README.md, the
-// PHP-specific ../README.md, and ../REFERENCE.md — extracts every fenced php
-// block (tagged by source doc + index) and enforces four properties:
-//
-//   1. SYNTAX — `php -l` on every block (a leading <?php is prepended when the
-//      snippet omits one). Every documented example must parse.
-//   2. RUN — every RUNNABLE block (one that constructs the SDK, drives
-//      $client->, or performs an entity op) is EXECUTED offline in seeded test
-//      mode against the real SDK. The captured stdout+stderr is scanned for
-//      FATAL programming-error markers REGARDLESS of exit code, so a bug that a
-//      documented try/catch swallows and echoes via getMessage() is still
-//      caught. Only a not-found / domain error is tolerated.
-//   3. COMPLETENESS — every block is partitioned into exactly one of
-//      {executed, syntaxchecked-nonrunnable, illustration} and the counts must
-//      sum to the total. "illustration" is a NARROW explicit class (a
-//      signature / method-table block that names the SDK class or a documented
-//      method but never uses a live client) — never a catch-all. A
-//      runnable-looking block that was NOT executed lands in neither bucket and
-//      FAILS the gate: no runnable example can be silently skipped.
-//   4. A per-doc summary (total / executed / syntaxchecked / illustration) is
-//      printed to STDERR.
-//
-// A runnable block is rewritten so its client is a test-mode client
-// (<Sdk>SDK::test) seeded with an in-memory fixture for every entity it
-// references; any real constructor is rewritten and the doc's own require of
-// the SDK file is stripped (we require it by absolute path). A block that only
-// *uses* $client (constructed in an earlier fenced block) gets a test client
-// prepended.
-//
-// The emitted PHP builds the ``` fence via chr(96) so this generator string
-// contains no backticks of its own.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target } = props
   const { model } = props.ctx$

package/project/.sdk/src/cmp/php/ReadmeExplanation_php.ts

@@ -20,6 +20,7 @@ Use \`Helpers::to_map()\` to safely validate that a value is an array.
 php/
 ├── ${model.const.Name.toLowerCase()}_sdk.php          -- Main SDK class
 ├── config.php                     -- Configuration
+├── schema.php                     -- Generated option + entity specs
 ├── features.php                   -- Feature factory
 ├── core/                          -- Core types and context
 ├── entity/                        -- Entity implementations

package/project/.sdk/src/cmp/php/ReadmeHowto_php.ts

@@ -4,7 +4,6 @@ import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityId
 import { KIT, getModelPath, nom } from '@voxgig/apidef'
 
 
-// A type-correct PHP literal for a field's canonical type.
 function phpLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'

package/project/.sdk/src/cmp/php/ReadmeQuick_php.ts

@@ -15,9 +15,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
     e.active !== false &&
     e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
@@ -132,9 +129,6 @@ try {
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -160,29 +154,18 @@ try {
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are PHP-typed by the
-    // field's canonical type. ids are rendered separately as the match key for
-    // update/remove; a REQUIRED create id stays (the call is invalid without
-    // it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
       return chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type, 'example_' + it.name)}`)
     }
 
-    // The id VALUE for an update/remove match: off the returned `$created`
-    // record only when its data type carries the id AND a create ran, else a
-    // type-correct literal.
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
@@ -211,8 +194,6 @@ $client->${phpEntityAccessor(eName)}()->update([${updatePairs.join(', ')}]);
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/php/ReadmeRef_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -55,7 +55,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -193,7 +193,6 @@ $${ent.name} = $client->${phpEntityAccessor(ent.Name)}();
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -256,7 +255,6 @@ ${info.desc}
 
 `)
 
-          // Show example
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
             // like page_id) — the same shape the runtime resolves path
@@ -391,9 +389,6 @@ $client = new ${model.const.Name}SDK([
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }