@voxgig/sdkgen 4.2.4 → 4.2.5

package/src/sdkgen.ts

@@ -73,6 +73,7 @@ import {
   srcFeatureExcludes,
 } from './helpers/featureSource'
 import type { FeatureSource } from './helpers/featureSource'
+import { stationLibrary } from './helpers/station'
 import {
   definitionPath,
   definitionFolder,
@@ -299,7 +300,13 @@ function SdkGen(opts: SdkGenOptions) {
     // so resolve it ONCE: every destination is compared against it, and a
     // comparison between a relative and an absolute path is meaningless.
     const root = Path.resolve(folder)
-    const external = externalItems(model, root, ['target', 'docs'])
+    // Snapshot the decision before preflight. In particular, do not check a
+    // missing optional destination once for safety and AGAIN before writing:
+    // if it appeared between those checks, the pass could write into content
+    // that was never ownership-validated.
+    const external: ExternalPlan[] =
+      externalItems(model, root, ['target', 'docs'])
+        .map((ext) => ({ ...ext, skip: externalSkipReason(ext, fs) }))
 
     // Before ANY file is written, in-tree included: a destination that turns
     // out to be wrong must abort the whole generation, not leave half of it
@@ -382,17 +389,13 @@ function SdkGen(opts: SdkGenOptions) {
     }
 
     for (const ext of external) {
-      // `active: false` is the project's only lever to stop the generator
-      // writing into a repo it does not own, so it has to be honoured HERE —
-      // the consumer Root iterates targets raw and does not check it. The
-      // target is still removed from the in-tree model above (withoutExternal
-      // takes every `output: path` target, active or not), so switching one
-      // off generates it nowhere rather than relocating it into
-      // `<sdk-repo>/<target>/`.
-      if (!ext.active) {
+      // A skipped external target is still removed from the in-tree model
+      // above: neither `active: false` nor a missing `output.create: false`
+      // destination may relocate it into `<sdk-repo>/<target>/`.
+      if (null != ext.skip) {
         log.info({
           point: 'generate-external-skip', target: ext.name, folder: ext.folder,
-          note: ext.name + ' inactive, not generated'
+          note: ext.skip
         })
         continue
       }
@@ -673,6 +676,13 @@ type ExternalSpec = {
 }
 
 
+type ExternalPlan = ExternalSpec & {
+  // Snapshotted before destination validation and consumed unchanged by the
+  // generation loop, so a filesystem race cannot bypass the safety guard.
+  skip: string | null
+}
+
+
 // Targets declaring `output: path` — generated into their own repo rather
 // than into `<sdk-repo>/<target>/`.
 //
@@ -715,6 +725,32 @@ function externalItems(
 }
 
 
+// Why this external item should not get a generation pass RIGHT NOW.
+//
+// `active: false` disables the target itself. `output.create: false` does
+// something deliberately narrower: the target stays active in the model but
+// an absent destination is treated as an optional checkout rather than a
+// folder sdkgen should fabricate. If that repo is checked out later, the same
+// unchanged model generates it normally.
+//
+// Snapshotted into ExternalPlan because both the pre-write destination guard
+// and the actual pass must make the identical decision. If the guard skipped
+// an item that the pass did not, generation could write outside the project
+// without any of the ownership checks below.
+function externalSkipReason(ext: ExternalSpec, fs: any): string | null {
+  if (!ext.active) {
+    return ext.name + ' inactive, not generated'
+  }
+
+  if (false === ext.target.output?.create && !fs.existsSync(ext.folder)) {
+    return ext.name + ' output folder does not exist and ' +
+      'output.create=false, not generated'
+  }
+
+  return null
+}
+
+
 // The `.jostraca` bookkeeping tree (meta log + a duplicate of the last
 // generated output) that jostraca leaves at an output root. It is the only
 // on-disk evidence that this toolchain has generated into a directory
@@ -754,14 +790,14 @@ const EXTERNAL_MARKER = '.jostraca'
 // generating somewhere other than it believes must be told. A destination
 // that legitimately holds other content first (a repo seeded with a README
 // and LICENCE) says so once in the model, with `output: adopt: true`.
-function checkExternalFolders(external: ExternalSpec[], root: string, fs: any) {
+function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
   const claimed: Record<string, string> = {}
 
   for (const ext of external) {
-    // An inactive target writes nothing, so its destination is not a hazard —
-    // and switching a target off must not require keeping its now-unused
-    // path valid.
-    if (!ext.active) continue
+    // A skipped item writes nothing, so its destination is not a hazard. The
+    // snapshotted decision gates the actual pass too; keeping it identical is
+    // what makes the pre-write check complete.
+    if (null != ext.skip) continue
 
     const label = ext.kind.charAt(0).toUpperCase() + ext.kind.slice(1)
 
@@ -1107,6 +1143,7 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  stationLibrary,
 
   definitionPath,
   definitionFolder,

package/src/types.ts

@@ -47,6 +47,11 @@ type ModelFeature = NameCases & {
   active?: boolean
   title?: string
   version?: string
+  // Transport role (station design §8.4): 'base' replaces the transport
+  // slot (only `test`), 'wrap' wraps it, 'none' is hook-only. Schema
+  // default is 'none'; configDefinition carries it into the embedded
+  // config beside the feature's `config.options`.
+  transport?: string
   hook?: Record<string, ModelHook>
   deps?: Record<string, Record<string, ModelDep>>
   [extra: string]: any
@@ -71,6 +76,7 @@ type ModelTarget = NameCases & {
   output?: {
     path?: string
     repo?: string
+    create?: boolean
     adopt?: boolean
     sdkrel?: string
   }

package/src/utility.ts

@@ -318,7 +318,21 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
 
   const featureDefs: any = {}
   each(feature, (f: any) => {
-    featureDefs[f.name] = f.config || {}
+    // The feature's declared config (its `options` key set with typed
+    // defaults) PLUS its transport role (station design §8.4): 'base'
+    // replaces the transport slot, 'wrap' wraps it, 'none' is hook-only.
+    // Station's descriptor (normalizeDescriptor in voxgig/station) reads
+    // `transport` beside `options` to validate the resolved feature order.
+    // The role is DECLARED in the feature model, never inferred - an empty
+    // `hook: {}` is wrong for station, which both wraps and dispatches
+    // hooks. Additive: a model unified without the schema's `transport`
+    // default simply omits the key, which station tolerates by degrading
+    // its role checks to nothing.
+    const fdef: any = { ...(f.config || {}) }
+    if (null != f.transport && '' !== f.transport) {
+      fdef.transport = String(f.transport)
+    }
+    featureDefs[f.name] = fdef
   })
 
   const options: any = { base: baseUrl }