@voxgig/sdkgen 4.21.0 → 4.22.0

package/project/.sdk/src/cmp/kotlin/PrepareAuth_kotlin.ts

@@ -15,39 +15,6 @@ import {
 import { kotlinPackage } from './utility_kotlin'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// 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, hardcoding an `authorization` header. 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 ts port (PrepareAuth_ts) is the donor.
-//
-// KOTLIN IS AN EXTRACTION, NOT A REPLACEMENT. The other twelve targets had
-// a `prepare_auth` template of their own to delete; kotlin did not — the
-// function lived among eight unrelated `prepare*` helpers in
-// `tm/kotlin/utility/Prepare.kt`. So `prepareAuth` (and only it, with the
-// three constants nothing else in that file used) MOVES here, into its own
-// compilation unit in the SAME package.
-//
-// That is a pure move as far as every caller is concerned, because a
-// Kotlin top-level function is visible to the whole package without an
-// import: `utility/Register.kt` keeps binding `u.prepareAuth = ::prepareAuth`
-// unchanged, `core/Utility.kt` keeps its `lateinit var prepareAuth:
-// (Context) -> Spec` and its `u.prepareAuth = this.prepareAuth` copy, and
-// `core/SdkClient.kt` and `utility/MakeSpecUrl.kt` keep calling
-// `utility.prepareAuth(ctx)` through that binding. Nothing is renamed and
-// nothing is re-wired. The three constants were `private` (file-scoped), so
-// carrying them here cannot collide with what stays behind.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -56,46 +23,13 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
 
   const where = resolveAuthIn(model)
 
-  // LOWERCASED FOR A HEADER, VERBATIM OTHERWISE. `spec.headers` is a
-  // LinkedHashMap<String, Any?> — case-SENSITIVE — and every other writer
-  // and reader of an auth header in this target spells it lower case: the
-  // deleted template's own `HEADER_AUTH = "authorization"`, SecretsFeature's
-  // `headers["authorization"]` rewrite and removal, DebugFeature's redact
-  // list, PipelineTest's assertions, and the shared corpus's
-  // `ctx:spec:headers:authorization`. apidef writes `name: "Authorization"`,
-  // so emitting it verbatim would put the credential under a key none of
-  // those touch — a second header beside the one they manage rather than
-  // the one they manage. Header names are case-insensitive on the wire
-  // (RFC 7230) and lower case on HTTP/2, so nothing is lost. Query
-  // parameters and cookies ARE case-sensitive and keep the spec's spelling.
   const resolved = resolveAuthName(model)
   const name = 'header' === where ? resolved.toLowerCase() : resolved
 
   const basic = isHttpBasicAuth(model)
 
-  // Read so the resolution is visible at generation time even though the
-  // emitted code takes the prefix from options at runtime (the secrets
-  // feature rewrites it there).
   const prefix = resolveAuthPrefix(model)
 
-  // FOLDER NESTING, worked out from the template's own path and from
-  // Main_kotlin's call site.
-  //
-  // Main_kotlin's `Copy({ from: 'tm/kotlin', exclude: [/src\//] })` runs at
-  // Main's TOP LEVEL, so `tm/kotlin/utility/Prepare.kt` lands at
-  // `<out>/utility/Prepare.kt` — and `build.gradle.kts` declares
-  // `sourceSets["main"].kotlin.setSrcDirs(listOf("core", "utility",
-  // "feature", "entity"))`, four SIBLING roots at the target root. So this
-  // component opens exactly ONE segment, `utility`, and Main must call it
-  // from its top level — NOT from inside `Folder({ name: 'core' })`, where
-  // Config and SdkError are written.
-  //
-  // Nested there it would write `core/utility/PrepareAuth.kt`, and that
-  // mistake is INVISIBLE to a compile: `core` is itself a source root and
-  // gradle scans it recursively, so the misplaced file would still be
-  // compiled and its `package <pkg>.utility` declaration would still make
-  // `::prepareAuth` resolve. The tree would simply be wrong — a utility
-  // file filed under core — with nothing to report it.
   Folder({ name: 'utility' }, () => {
     File({ name: 'PrepareAuth.' + target.ext }, () => {
       Content(render({
@@ -122,31 +56,6 @@ type AuthSpec = {
 
 
 function render(spec: AuthSpec): string {
-  // NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING.
-  //
-  // `isAuthActive` answers two different questions with one boolean:
-  //
-  //   1. `main.kit.config.auth.active: false` — this SDK is deliberately
-  //      built WITHOUT auth. A per-SDK decision by the project.
-  //   2. `main.kit.info.auth: false`          — the SPEC declares no
-  //      security scheme. A fact about the API definition.
-  //
-  // Only (1) may silence prepareAuth. (2) says nothing about whether the
-  // CALLER holds a credential, and kotlin has always let one through: the
-  // optspec in `tm/kotlin/utility/MakeOptions.kt` supplies an
-  // `"auth": { "prefix": "" }` default whether or not the generated Config
-  // carries one, so `options["auth"]` is non-null at runtime, the
-  // template's `options["auth"] == null` guard never fired, and the
-  // credential was placed regardless of what the spec declared. The
-  // generated secrets feature depends on exactly that — it resolves a
-  // secret into `options.apikey` and expects prepareAuth to place it — and
-  // so does generatedcompile's `kotlin: auth null beats an explicit apikey`
-  // lane, whose baseline ("an ordinary apikey IS sent") is unsatisfiable
-  // the moment the wider gate is used.
-  //
-  // `isAuthSuppressed` is the narrow one: `main.kit.config.auth.active ===
-  // false` and nothing else. A spec that is merely silent keeps the
-  // credential path it has always had.
   if (spec.suppressed) {
     return head(spec) + `import ${spec.kotlinpackage}.core.Context
 import ${spec.kotlinpackage}.core.Spec
@@ -176,9 +85,6 @@ function head(spec: AuthSpec): string {
 }
 
 
-// The credential-absent test, identical in all three placements and
-// identical to the template's. Kept as one string so a placement cannot
-// drift from the others on what "no credential" means.
 const SKIP = `  var skip = false
   if (apikey == null) {
     skip = true
@@ -246,15 +152,6 @@ fun prepareAuth(ctx: Context): Spec {
 }
 
 
-// HTTP BASIC IS HEADER-ONLY BY DEFINITION: the scheme is
-// `Authorization: Basic base64(user:pass)`. It cannot be expressed as a
-// query parameter or a cookie, so the branch is emitted only from
-// renderHeader, and only when the model says this API actually uses it — a
-// bearer SDK carries none of it.
-//
-// `Struct.getpath` returns the UNDEF sentinel, not null, for a path the map
-// does not have, so the switch is read with `is Boolean` rather than
-// compared against `true`: the sentinel is neither.
 function basicBlock(spec: AuthSpec): string {
   if (!spec.basic) return ''
 
@@ -293,10 +190,6 @@ function basicBlock(spec: AuthSpec): string {
 }
 
 
-// QUERY. MakeSpecUrl fills `spec.query` (prepareQuery) BEFORE it calls
-// prepareAuth, and makeUrl reads `spec.query` afterwards, url-escaping every
-// key and value onto the URL — so the credential placed here reaches the
-// wire as `?name=value`. The headers are never touched.
 function renderQuery(spec: AuthSpec): string {
   return head(spec) + `import ${spec.kotlinpackage}.core.Context
 import ${spec.kotlinpackage}.core.Spec
@@ -339,12 +232,6 @@ fun prepareAuth(ctx: Context): Spec {
 }
 
 
-// COOKIE. A cookie IS a header, so the credential rides the header bag —
-// but the `cookie` header is SHARED with whatever cookies options.headers
-// (or an earlier feature) put there, so our pair is SPLICED in and out
-// rather than the header assigned over. Splicing also makes this
-// idempotent: a retried request cannot end up carrying the credential
-// twice.
 function renderCookie(spec: AuthSpec): string {
   return head(spec) + `import ${spec.kotlinpackage}.core.Context
 import ${spec.kotlinpackage}.core.Spec

package/project/.sdk/src/cmp/kotlin/ReadmeEntity_kotlin.ts

@@ -11,7 +11,6 @@ import { kotlinVarName } from './utility_kotlin'
 
 // Type names come from the shared canonToType 'kotlin' column (single source of truth).
 
-// A type-correct Kotlin literal for a field's canonical type.
 function kotlinLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'

package/project/.sdk/src/cmp/kotlin/ReadmeExamplesTest_kotlin.ts

@@ -4,26 +4,6 @@ import { cmp, File, Content } from '@voxgig/sdkgen'
 import { kotlinPackage } from './utility_kotlin'
 
 
-// Emits test/ReadmeExamplesTest.kt — a JUnit PRESENCE + STRUCTURE gate over
-// every ```kotlin fenced block in the repository ROOT README.md, the
-// per-language kotlin/README.md, AND the per-language kotlin/REFERENCE.md.
-//
-// SCOPE NOTE (deliberate, documented): the Python/TS/Go equivalents EXECUTE and
-// type-check every documented block. That is infeasible here — the generated
-// Kotlin SDK compiles with Gradle/kotlinc only (no in-process Kotlin compiler
-// dependency wired into the test classpath), so a test cannot compile-and-run
-// arbitrary doc snippets at test time. This gate therefore guarantees the
-// weaker-but-real invariant that keeps the docs honest as the generator evolves:
-//   1. every doc exists and contains at least one ```kotlin block (nothing was
-//      dropped);
-//   2. every ```kotlin block is structurally well-formed — its braces,
-//      parentheses and brackets balance (catches a truncated or malformed
-//      generated snippet).
-// A per-doc summary line makes the coverage visible in the test output.
-//
-// The emitted Kotlin is written WITHOUT literal backticks (the fence marker is
-// built at runtime as 96.toChar().toString().repeat(3)) so this TS template
-// literal stays clean.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

package/project/.sdk/src/cmp/kotlin/ReadmeRef_kotlin.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -60,7 +60,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const SDK = model.const.Name + 'SDK'
 
   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)
 
@@ -377,9 +377,6 @@ val client = ${SDK}(mutableMapOf<String, Any?>("feature" to feature))
 \`\`\`
 
 `)
-      // 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 })
     }
 

package/project/.sdk/src/cmp/kotlin/ReadmeTopQuick_kotlin.ts

@@ -54,15 +54,10 @@ import ${kotlinPackage(model)}.core.${SDK}
   }
 
   if (exampleEntity) {
-    // Sanitise the local variable name — an entity whose camelCased name is a
-    // Kotlin keyword gets a trailing underscore (kotlinVarName) so the snippet
-    // compiles.
     const eVar = kotlinVarName(exampleEntity.name)
     const accessor = kotlinVarName(exampleEntity.name)
     const eNameLower = nom(exampleEntity, 'Name').toLowerCase()
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes an empty match.
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {

package/project/.sdk/src/cmp/kotlin/Schema_kotlin.ts

@@ -18,25 +18,6 @@ import {
 } from './utility_kotlin'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// The kotlin peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
-// optspec from `main.kit.optspec` plus each feature's own `config.options`,
-// entityspec from the entity field sentinels — both built by the shared
-// helpers, so what kotlin validates against and what ts validates against
-// cannot drift.
-//
-// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal: JSON is
-// a subset of TypeScript's own literal syntax and is not a subset of
-// kotlin's. Chunked StringBuilder appends, exactly as Config.kt carries its
-// config, keep every string constant far below the JVM's 64KB limit no matter
-// how many features or entities the model grows.
-//
-// The round-trip is exact because the spec holds only strings and booleans:
-// pinned by "strings and booleans only, so the JSON round-trip is lossless"
-// in ts/test/optspec.test.ts. That is not incidental — Json.parse decodes a
-// JSON number to one kotlin type and struct reads a spec BY EXAMPLE, so one
-// number in here would mean something different in kotlin than in ts.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target

package/project/.sdk/src/cmp/kotlin/TestEntity_kotlin.ts

@@ -152,10 +152,6 @@ ${allSteps.length > 0 ? `    val client = setup.client\n\n` : ''}`)
 
 `)
 
-    // Stream test (PR #4): the entity `stream` method runs the op pipeline and
-    // returns a Sequence. With the streaming feature active it yields from the
-    // feature's incremental iterator; otherwise it falls back to the
-    // materialised items. Only emitted for entities whose flow lists.
     const flowHasList = allSteps.some((s: any) => s.op === 'list')
     if (flowHasList) {
       Content(`  @Test

package/project/.sdk/src/cmp/kotlin/Test_kotlin.ts

@@ -24,12 +24,6 @@ const Test = cmp(function Test(props: any) {
     // Write-once: a project's edited control file survives regeneration.
     TestControl({ target, dir: 'test' })
 
-    // The shared test infrastructure (RunnerSupport, the vendored omni
-    // runner under test/vendor/omni with its OmniResolver/OmniSmokeTest,
-    // FeatureHarness, PipelineTest, FeatureTest, NetsimTest,
-    // PrimaryUtilityTest, CustomUtilityTest, StructCorpusTest, ExistsTest
-    // and sdk-test-control.json) ships as templates in tm/kotlin/test/ and
-    // is copied by Main_kotlin. Here we generate only the API-specific tests.
     const entity = each(entityCollection(model))
       .filter((e: any) => false !== e.active)
     each(entity, (entity: ModelEntity) => {

package/project/.sdk/src/cmp/kotlin/utility_kotlin.ts

@@ -34,7 +34,6 @@ function kotlinPackage(model: any): string {
 }
 
 
-// Maven/Gradle group coordinates for the generated SDK (used by Package_kotlin).
 function gradleGroup(model: any): string {
   const org = String(model.origin || 'voxgig-sdk')
     .replace(/-sdk$/, '')
@@ -45,7 +44,6 @@ function gradleGroup(model: any): string {
 
 
 const KOTLIN_KEYWORDS = new Set([
-  // hard keywords
   'as', 'break', 'class', 'continue', 'do', 'else', 'false', 'for', 'fun',
   'if', 'in', 'interface', 'is', 'null', 'object', 'package', 'return',
   'super', 'this', 'throw', 'true', 'try', 'typealias', 'typeof', 'val',
@@ -53,9 +51,6 @@ const KOTLIN_KEYWORDS = new Set([
 ])
 
 
-// A camelCase Kotlin identifier for a snake_case model name
-// (`status_embed_config` -> `statusEmbedConfig`), with a reserved-word
-// guard (a `fun`/`class` entity must not bind a Kotlin keyword).
 function kotlinVarName(name: string): string {
   const pascal = camelify(name)
   const out = pascal.charAt(0).toLowerCase() + pascal.slice(1)
@@ -63,42 +58,14 @@ function kotlinVarName(name: string): string {
 }
 
 
-// Strip model bookkeeping keys (ending in $) from a config subtree.
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
-// Keys whose value IS the default the runtime already assumes when the key is
-// absent, so emitting them is pure payload.
 const CONFIG_DEFAULT: Record<string, any> = {
   active: true,
   req: false,
   reqd: false,
 }
 
-// Subtrees carrying user payload rather than schema. An active:true inside an
-// OpenAPI example is DATA, not a default, so default-pruning stops at these
-// keys and everything below them is passed through untouched.
 const PAYLOAD_KEYS = ['default', 'example', 'examples']
 
 function cleanModel(o: any, dropDefaults?: boolean): any {

package/project/.sdk/src/cmp/lua/Config_lua.ts

@@ -35,21 +35,6 @@ import {
 } from './utility_lua'
 
 
-// PLUGIN DEFINITION REQUIRES AND THE FEATURE PLUGINS TABLE (the lua peer
-// of 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 the generated
-// config_plugins module requires each active plugin's module and names the
-// FIELD it exports (the model's `def.lua` map - `hashicorp` on
-// plugins/hashicorp.lua, `awssecrets` AND `awsparams` on plugins/aws.lua),
-// handing the list to the feature.
-//
-// A def value is the module's path under tm/lua, this target's root; the
-// require is that path with `.lua` stripped and slashes turned to dots,
-// resolved by the plain `?.lua` searcher every generated lua SDK relies on.
-// One `local` per module, so a two-definition module is required once.
 function pluginRequires(feature: any): { locals: string[], defs: Record<string, string[]> } {
   const bypath: Record<string, { local: string, syms: string[] }> = {}
   const defs: Record<string, string[]> = {}
@@ -94,36 +79,22 @@ 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)
 
   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 make_options).
   const svars = serverVariables(model)
   const serverBlock = 0 === svars.length ? '' :
     '      server = {\n' +
     svars.map((v: any) => `        [${JSON.stringify(v.name)}] = ${JSON.stringify(v.dflt)},\n`).join('') +
     '      },\n'
 
-  // WHERE the credential goes and UNDER WHAT NAME. apidef resolved both
-  // from the spec's securityScheme all along and generation dropped them,
-  // so an apiKey-in-query API got an authorization header it does not read.
-  // Emitted only when they differ from the defaults, so a
-  // header/Authorization SDK is byte-identical to what it generated before.
-  //
-  // `in` is a RESERVED WORD in lua, so the key is bracketed - a bare
-  // `in = "query"` does not parse.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
   const authBlock = authActive
@@ -134,13 +105,6 @@ 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 this target into the main slug/version/target identity
-  // fields (station descriptor v1 reads all three) - the literal branch
-  // below emits them too, so the two representations cannot diverge.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -150,18 +114,6 @@ const Config = cmp(async function Config(props: any) {
 
 `)
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // A table constructor makes the Lua parser emit a SETTABLE per entry and
-    // the VM run them all on every load; a long-bracket string is one token,
-    // and dkjson's decoder builds the table from it.
-    //
-    // dkjson is already a runtime dependency - `utility/fetcher.lua` decodes
-    // every HTTP response with it - so this adds nothing to the SDK.
-    //
-    // Null handling agrees between the branches by construction: dkjson maps
-    // JSON null to nil, and assigning nil to a table key removes it, which is
-    // exactly what the literal branch does when `formatLuaTable` emits `nil`.
     if (asData) {
       Content(`local json = require("dkjson")
 
@@ -253,14 +205,6 @@ return make_config
 `)
   })
 
-  // The plugin definitions the model selected per feature, as a module of
-  // the config family. ALWAYS emitted, even with nothing declared: the
-  // secrets feature requires it (a missing module and a broken one must
-  // read differently there), and a feature source arrives in the tree by
-  // Main's blanket copy whether or not the model declares the feature.
-  //
-  // A sibling module rather than a member of `config`, for the reason
-  // config_shared is: `config` returns a bare function.
   const plugins = pluginRequires(feature)
 
   File({ name: 'config_plugins.' + target.ext }, () => {

package/project/.sdk/src/cmp/lua/EntityTypes_lua.ts

@@ -1,20 +1,5 @@
 
 
-// Typed-model generator (Lua target).
-//
-// Lua is dynamically typed, so the "types" are LuaLS annotations
-// (---@class / ---@field) for editor/tooling DX only — no runtime effect.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file, <sdk>_types.lua,
-// with a `---@class <Name>` per active entity plus a request/match ---@class
-// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned
-// into LuaLS types by the shared sdkgen helper `canonToType` ('lua' column).
-//
-// Keeps the SAME type-name scheme as the TS reference (<Name>,
-// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
-// <Name>RemoveMatch). The op fragments reference these class names via
-// ---@param / ---@return.
 
 import {
   cmp, each, names,
@@ -32,8 +17,6 @@ import {
 const LANG = 'lua'
 
 
-// A bare LuaLS field key, or a bracketed string literal for anything that is
-// not a plain Lua identifier.
 function propKey(name: string): string {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : '[' + JSON.stringify(name) + ']'
 }
@@ -43,10 +26,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   const { target } = props
   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
@@ -58,9 +37,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)
 
   File({ name: model.name + '_types.' + (target.ext || LANG) }, () => {
@@ -80,7 +56,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       const fields = (ent.fields ? each(ent.fields) : [])
         .filter((f: any) => f.active !== false)
 
-      // Entity data model: one ---@field per field, `req:false` -> optional (?).
       Content(`---@class ${Name}
 `)
       fields.forEach((f: any) => {
@@ -91,9 +66,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       Content(`
 `)
 
-      // Per active op: a request/match class. Members and their optionality
-      // come from the shared partiality policy (opRequestShape); this file only
-      // renders them as LuaLS ---@field lines.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
@@ -115,8 +87,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       })
     })
 
-    // Make the file a require-able (empty) module. The blank line above keeps
-    // LuaLS from binding the last ---@class to this local.
     Content(`local M = {}
 
 return M

package/project/.sdk/src/cmp/lua/Entity_lua.ts

@@ -35,7 +35,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/lua/fragment/')
 
-  // Entity files go to entity/ folder
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -58,14 +57,8 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.lua so the class can be renamed independently.
           EntyClass: cls,
 
-          // Feature-hook wiring: the built-in `#Name-Hook` tag replacement
-          // is hardwired to `//` line comments, so Lua's `-- #PrePoint-Hook`
-          // markers were never matched and no pipeline hooks fired in
-          // generated code. Match the Lua-comment hook tags explicitly.
           '/(?<indent>[ \\t]*)-- #(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\n?/':
             ({ name, indent }: any) =>
               `${indent}utility.feature_hook(ctx, "${name}")\n`,