@voxgig/sdkgen 3.4.6 → 3.5.0

package/src/action/target.ts

@@ -6,17 +6,19 @@ import {
   Folder,
   Copy,
   File,
+  Content,
   cmp,
   each,
+  template,
 } from 'jostraca'
 
 import { showChanges } from '@voxgig/util'
 
 import { showDryrun } from '../helpers/dryrun'
 
-import { templateReplacements } from '../helpers/stdrep'
+import { templateReplacements, provenanceReplace } from '../helpers/stdrep'
 
-import { getelem } from '@voxgig/struct'
+import { isJunk, copyOpts } from '../helpers/junk'
 
 import { Aontu } from 'aontu'
 
@@ -32,6 +34,7 @@ import type {
 import { SdkGenError } from '../utility'
 
 import {
+  BASE_FEATURE,
   availableFeatures,
   findFeatureSources,
   featureExcludes,
@@ -48,6 +51,10 @@ import {
   loadContent,
 } from './action'
 
+import { kindModel, resolveKind, escapeRe } from './kind'
+
+import { BUNDLED, resolveSource, registerInstalled } from './resolve'
+
 
 const CMD_MAP: any = {
   add: cmd_target_add
@@ -99,6 +106,10 @@ async function target_add(targets: string[], actx: ActionContext): Promise<Actio
     control: {
       dryrun: !!actx.opts.dryrun
     },
+    // Per-call for the same reason `control` is: this action runs on whatever
+    // Jostraca instance the caller handed it, and a template tree must not
+    // carry a maintainer's build droppings into a project. See helpers/junk.
+    cmp: copyOpts(),
   }
 
   opts.log.info({
@@ -131,9 +142,21 @@ async function target_add(targets: string[], actx: ActionContext): Promise<Actio
     showDryrun(opts.log, 'target-result', jres, actx.folder)
   }
 
-  // feature_add copies feature templates for targets already registered in
-  // the model. The targets added above are not in the in-memory model yet,
-  // so TargetRoot copies their feature templates itself.
+  // The targets just written are not in the in-memory model — nothing
+  // recompiles `model/sdk.aontu` mid-process — so put them there before the
+  // fan-out below.
+  //
+  // TargetRoot copies each new target's feature source from ITS OWN TREE,
+  // which is the whole story only while every feature ships in the same
+  // package as every target. For a feature supplied by a DIFFERENT package,
+  // the source lives in that package's overlay, and only `feature_add`'s
+  // two-tree lookup consults it — for targets in the model. So a target added
+  // while such a feature was already active got no source for it at all:
+  // TargetRoot could not find it, and the fan-out could not see the target.
+  registerInstalled('target', targets, actx)
+
+  // feature_add copies feature templates for every target in the model,
+  // which now includes the ones just added.
   await feature_add(features, actx)
 
   opts.log.info({
@@ -148,9 +171,15 @@ async function target_add(targets: string[], actx: ActionContext): Promise<Actio
 
 
 const TargetRoot = cmp(function TargetRoot(props: any) {
-  const { ctx$, targets, features } = props
+  const { ctx$, targets, features, actx } = props
   const { model, log } = ctx$
 
+  const fs = ctx$.fs()
+
+  // The prune below writes through `fs` directly rather than through
+  // jostraca, so it has to be told about the dry run itself.
+  const dryrun = !!actx?.opts?.dryrun
+
   // TODO: jostraca - make from value easier to specify 
   // const tfolder = 'node_modules/@voxgig/sdkgen/project/.sdk'
 
@@ -169,7 +198,13 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
         note: tref
       })
 
-      const { tname, tfolder, torigname, base } = resolveTarget(tref, ctx$)
+      // Resolved through the shared kind spine, so a BARE name follows what
+      // the model records exactly as a feature's does. Without that, a target
+      // installed from an external package resolved back to the bundled
+      // scaffold on its next `target add` — the same write-only-provenance
+      // trap features had.
+      const source = resolveKind(tref, 'target', ctx$)
+      const { name: tname, folder: tfolder, origname: torigname, base } = source
       tnames.push(tname)
       const targetNote = tname + (tname != tref ? ' ref:' + tref : '')
 
@@ -180,26 +215,34 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
         note: tname + (tname != torigname ? 'original' + torigname : '') + ' from:' + tfolder
       })
 
-      Folder({ name: 'model/target' }, () => {
-        Copy({
-          from: tfolder + '/model/target/' + torigname + '.aontu',
-          // exclude: true
-          replace: {
-            "'BASE'": "'" + base + "'"
-          }
-        })
-        File({ name: 'target-index.aontu' }, () => UpdateIndex({
-          content: ctx$.meta.content.target_index,
-          names: tnames,
-        }))
-      })
-
-      Folder({ name: 'src/cmp/' + tname }, () => {
-        Copy({
-          from: tfolder + '/src/cmp/' + torigname,
-          // exclude: true
+      // An ALIASED add (`target add go~go2`) installs the target under a new
+      // name, and every one of the three trees has to agree about that name.
+      const aliased = tname !== torigname
+
+      // The definition file and the index entry: the same for every kind, so
+      // they are emitted once, in action/kind.
+      Folder({ name: 'model/target' }, () => kindModel({
+        ctx$, kind: 'target', source, names: tnames,
+        content: ctx$.meta.content.target_index,
+      }))
+
+      if (aliased) {
+        // Components are dispatched by CONVENTION — `cmp/<t>/Main_<t>` — so
+        // an aliased tree whose files keep the origin suffix resolves
+        // nothing: `src/cmp/go2/Main_go.ts` is invisible to a lookup for
+        // `cmp/go2/Main_go2`. jostraca's tree Copy has no per-entry rename
+        // hook, so an aliased tree is emitted file by file instead.
+        aliasCmpTree(ctx$, tfolder + '/src/cmp/' + torigname,
+          'src/cmp/' + tname, torigname, tname)
+      }
+      else {
+        Folder({ name: 'src/cmp/' + tname }, () => {
+          Copy({
+            from: tfolder + '/src/cmp/' + torigname,
+            // exclude: true
+          })
         })
-      })
+      }
 
       // Copy the whole template tree MINUS the source of every feature the
       // model did not ask for. Which files those are is discovered from the
@@ -221,7 +264,8 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
       // package failed to compile — "fhHasFeature redeclared in this block".
       //
       // The invariant this restores: tm/<target> == source tree MINUS trim.
-      pruneStaleTemplates(ctx$, tfolder + '/tm/' + torigname, 'tm/' + tname, trim)
+      pruneStaleTemplates(
+        ctx$, tfolder + '/tm/' + torigname, 'tm/' + tname, trim, dryrun)
 
       Folder({ name: 'tm/' + tname }, () => {
         Copy({
@@ -241,6 +285,127 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
 })
 
 
+
+
+// `<Cmp>_<origname>.<ext>` -> `<Cmp>_<tname>.<ext>`, for an aliased install.
+// Anything not carrying the suffix (tsconfig.json, the fragment sources)
+// keeps its name — the `.<ext>` anchor is what keeps this off
+// `Main.fragment.go`, whose `go` is a file extension.
+//
+// Shared with doctor for the same reason as aliasCmpText: doctor walks the
+// ORIGIN tree to decide what should be present, so it has to land each file
+// under the same name the writer gave it, or it reports the whole tree as
+// missing.
+function aliasCmpName(name: string, torigname: string, tname: string): string {
+  return name.replace(
+    new RegExp('_' + escapeRe(torigname) + '(\\.[^.]+)$'), '_' + tname + '$1')
+}
+
+
+// The origin name a component carries INSIDE its source, rewritten for an
+// aliased install. Shared with doctor, which re-applies it before comparing —
+// same discipline as templateReplacements: a writer and a reader that
+// disagree by a character make every file read as a fork.
+//
+// Rewritten here rather than through jostraca's `replace` map, because that
+// map canonicalises each key into a regex group NAME — `_go'` and `_go"` both
+// reduce to the same name, so the later entry silently won and every
+// single-quoted import came out as `from './Package_go2"`. One explicit regex
+// keeps the quote it matched.
+// `cmpbase` is the component tree's PREFIX — `src/cmp/` for a target,
+// `src/cmp/docs/` for a docs item. Taken from the caller rather than fixed
+// here: a docs item's components live one level deeper, and a rewrite that
+// looked for `src/cmp/<orig>/` left an aliased docs component pointing at the
+// ORIGIN's fragments — reading them silently when both are installed.
+function aliasCmpText(
+  src: string, torigname: string, tname: string, cmpbase = 'src/cmp/',
+): string {
+  const orig = escapeRe(torigname)
+
+  return src
+    // The fragment directory, read relative to __dirname. The fragments are
+    // copied into the ALIAS's folder, so leaving the origin path would miss —
+    // or, if the origin target is also installed, silently read ITS fragments.
+    .replace(new RegExp(escapeRe(cmpbase) + orig + '/', 'g'), cmpbase + tname + '/')
+    // Sibling imports: `'./Package_go'` -> `'./Package_go2'`. Anchored on the
+    // closing quote (captured, so the style is preserved) to keep it off file
+    // EXTENSIONS — `Main.fragment.go` must not become `Main.fragment.go2`.
+    .replace(new RegExp('_' + orig + '([\'"])', 'g'), '_' + tname + '$1')
+}
+
+
+// Emit an aliased `src/cmp` tree: every file renamed from the origin suffix
+// to the installed one, and its CONTENT rewritten to match.
+//
+// Renaming alone would break the tree, because a component names its origin
+// twice over: sibling imports (`from './Package_go'`) and the fragment
+// directory it reads through `__dirname` (`/../../../src/cmp/go/fragment/`,
+// in 67 of the shipped components). Both are rewritten here — the fragment
+// path because the fragments are copied to the ALIAS's folder, so the origin
+// path would either miss or, worse, silently read the origin target's
+// fragments if that target is also installed.
+//
+// Files are emitted through jostraca (`File`/`Content`) rather than copied
+// with `fs`, so a dry run reports them and writes nothing, exactly as the
+// tree Copy on the unaliased path does.
+function aliasCmpTree(
+  ctx$: any,
+  fromDir: string,
+  toRel: string,
+  torigname: string,
+  tname: string,
+  cmpbase = 'src/cmp/',
+) {
+  const fs = ctx$.fs()
+
+  const aliasText = (src: string) =>
+    aliasCmpText(src, torigname, tname, cmpbase)
+
+  const emit = (dir: string, rel: string) => {
+    let entries: any[]
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    }
+    catch (e: any) {
+      return
+    }
+
+    // Sorted, so an aliased tree is emitted in the same byte-stable order
+    // everything else in this toolchain is. Junk is dropped here because this
+    // walk stands in for a tree Copy, which drops it through
+    // `cmp.Copy.ignore` — an aliased install must not be the one path that
+    // ships a maintainer's `__pycache__`. See helpers/junk.
+    const names = entries
+      .map((ent: any) => ent.name)
+      .filter((name: string) => !isJunk(name))
+      .sort()
+
+    for (const name of names) {
+      const child = Path.join(dir, name)
+      const ent = entries.find((e: any) => e.name === name)
+
+      if (ent.isDirectory()) {
+        Folder({ name }, () => emit(child, rel + '/' + name))
+        continue
+      }
+
+      const renamed = aliasCmpName(name, torigname, tname)
+
+      // `template` against the model with no replace map, matching what Copy
+      // does for the unaliased tree — jostraca's Copy always interpolates
+      // `$$ref$$` against the model, so an aliased tree must too.
+      const src = fs.readFileSync(child, 'utf8')
+
+      File({ name: renamed }, () => Content(template(aliasText(src), ctx$.model)))
+    }
+  }
+
+  Folder({ name: toRel }, () => emit(fromDir, toRel))
+}
+
+
+
+
 // Path patterns that keep a target's unwanted feature source out of the
 // project: the source of every AVAILABLE feature the model did not select,
 // plus the templates that only compile with the complete feature set.
@@ -274,6 +439,7 @@ function pruneStaleTemplates(
   fromDir: string,
   toRel: string,
   trim: RegExp[],
+  dryrun?: boolean,
 ) {
   const { log } = ctx$
   const fs = ctx$.fs()
@@ -291,6 +457,16 @@ function pruneStaleTemplates(
         return
       }
       for (const ent of entries) {
+        // Junk is invisible to this listing on BOTH sides, and it has to be
+        // both. In the source it is never copied, so counting it would want a
+        // file that can never arrive. In the destination it was never written
+        // by this toolchain, so counting it as stale would have `target add`
+        // delete a maintainer's own `__pycache__` out of their SDK repo —
+        // this prune's remit is the tree it writes, not the tree it finds.
+        if (isJunk(ent.name)) {
+          continue
+        }
+
         const child = Path.join(dir, ent.name)
         const childRel = '' === rel ? ent.name : rel + '/' + ent.name
         if (ent.isDirectory()) {
@@ -324,6 +500,29 @@ function pruneStaleTemplates(
     return
   }
 
+  // A DRY RUN must not delete. This prune calls `fs.unlinkSync` directly, and
+  // jostraca enforces `control.dryrun` only inside its own write layer — so
+  // `-y target add <t>` previewed the copies and then really removed every
+  // stale template, which is the opposite of what the flag promises and
+  // exactly the blast radius a maintainer runs `-y` to inspect. Report the
+  // deletions instead, in the same shape the copies are reported.
+  if (dryrun) {
+    log.info({
+      point: 'target-template-prune', target: toRel, count: stale.length,
+      files: stale, dryrun: true,
+      note: toRel + ': would remove ' + stale.length +
+        ' stale template(s) — ** DRY RUN **, nothing was written'
+    })
+    for (const rel of stale) {
+      log.info({
+        point: 'target-template-prune-file', target: toRel,
+        file: toRel + '/' + rel, dryrun: true,
+        note: 'would remove ' + toRel + '/' + rel
+      })
+    }
+    return
+  }
+
   const removed: string[] = []
   for (const rel of stale) {
     try {
@@ -349,6 +548,52 @@ function pruneStaleTemplates(
 }
 
 
+// WHICH NAMES COUNT AS FEATURE SOURCE, when deciding what to trim.
+//
+// This used to be the SOURCE folder's own `model/feature/` listing, which is
+// right only while every target ships in the same package as every feature.
+// An external target package declares no feature models of its own — it has
+// no reason to — so nothing was discovered, nothing was trimmed, and the
+// consumer received the target's source for EVERY feature regardless of what
+// its model selected. Measured on a target copied from the bundled `go`: the
+// bundled one keeps 2 feature source files, the external one kept all 18.
+//
+// That is the failure `helpers/featureSource` was written to end (272 stray
+// files in one repo), arriving again by the one route it did not cover.
+//
+// The catalogue is therefore the union of every place a feature this project
+// could select can come from:
+//
+//   - the bundled scaffold, which is what a bare `feature add <name>` means;
+//   - the source package's own declarations, for a package shipping both;
+//   - the consumer's OWN installed feature models, which is how an EXTERNAL
+//     feature's source becomes trimmable at all.
+//
+// Every term is a place feature DEFINITIONS live, deliberately. Taking the
+// third from the model's feature KEYS instead would make any name a project
+// happens to declare a trim candidate — and a file in a `feature/` directory
+// is not necessarily a feature. `tm/rust/feature/support.rs` and its siblings
+// are shared machinery that `Main_rust` emits unconditionally (`pub mod
+// support`), so a project that declared a feature called `support` would have
+// had that file pruned and produced a crate that cannot compile. A definition
+// file is evidence that the name really denotes a feature; a model key is not.
+//
+// For a bundled add this is `bundled ∪ bundled ∪ (⊆ bundled)`, so the trim is
+// byte-identical to what it always was — the goldens hold it to that.
+function featureCatalogue(ctx$: any, tfolder: string): string[] {
+  const fs = ctx$.fs()
+  const root = ctx$.folder ?? '.'
+
+  const names = new Set<string>([
+    ...availableFeatures(fs, Path.join(root, BUNDLED)),
+    ...availableFeatures(fs, tfolder),
+    ...availableFeatures(fs, root),
+  ])
+
+  return Array.from(names).sort()
+}
+
+
 function trimFeatures(
   ctx$: any,
   tfolder: string,
@@ -371,9 +616,9 @@ function trimFeatures(
 
   // `base` is not a declared feature — it is the always-present foundation
   // every other feature builds on — so it is never a trim candidate.
-  const selected = new Set(['base', ...(features ?? [])])
+  const selected = new Set([BASE_FEATURE, ...(features ?? [])])
 
-  const available = availableFeatures(fs, tfolder)
+  const available = featureCatalogue(ctx$, tfolder)
   const drop = findFeatureSources(fs, tfolder + '/tm/' + torigname, available)
     .filter((s) => !selected.has(s.name))
 
@@ -440,95 +685,32 @@ function readTargetFeature(
 }
 
 
-// Last path segment of a ref. A ref may be a bare target name ('go'), a
-// package-relative path ('@acme/kit/go'), or an ABSOLUTE path — and on Windows
-// an absolute path is separated by `\`, so splitting on '/' alone hands back
-// the whole path as the target name and every tree lookup below then misses.
-// On POSIX Path.sep IS '/', so this is the same split it always was.
-function lastSegment(ref: string): string {
-  return getelem(ref.split('/').flatMap((p: string) => p.split(Path.sep)), -1)
-}
-
-
+// `target add`'s view of the shared resolver: the same resolution every kind
+// uses, with this action's historical field names. Kept as a wrapper so its
+// callers (TargetRoot, doctor) and their tests do not have to move with the
+// extraction.
 function resolveTarget(tref: string, ctx$: any) {
-  let tname = tref
-  let torigname = tref
-  let tfolder = 'node_modules/@voxgig/sdkgen/project/.sdk'
-
-  const root = ctx$.folder
-  const fs = ctx$.fs()
-
-  let fulltfolder = Path.normalize(Path.join(root, tfolder))
-  tname = lastSegment(tref)
+  const src = resolveSource(tref, 'target', ctx$)
 
-  let aliasref = tref
-  torigname = lastSegment(aliasref)
-  const aliasing = tref.split('~')
-  if (1 < aliasing.length) {
-    aliasref = aliasing[0]
-    tname = aliasing.slice(1).join('~')
-    torigname = lastSegment(aliasref)
-  }
-
-  const search: string[] = []
-  let found = false
-  // Windows: an absolute ref is `D:\a\...` or `D:/a/...`, and a Path.join'd
-  // one carries backslashes, so neither `includes('/')` nor `startsWith('/')`
-  // recognises it. Path.isAbsolute and Path.sep are platform-correct and
-  // reduce to the same answers on POSIX.
-  if (aliasref.includes('/') || aliasref.includes(Path.sep)) {
-    // NOTE: the last path element of the ref is the target name, not a folder.
-    const aliasbase = Path.dirname(aliasref)
-
-    if (!Path.isAbsolute(aliasref)) {
-      fulltfolder = Path.normalize(Path.join(root, 'node_modules', aliasbase, '.sdk'))
-      search.push(fulltfolder)
-      found = fs.existsSync(fulltfolder)
-
-      if (!found) {
-        fulltfolder = Path.normalize(Path.join(root, aliasbase, '.sdk'))
-        search.push(fulltfolder)
-        found = fs.existsSync(fulltfolder)
-      }
-    }
-    else {
-      fulltfolder = Path.normalize(Path.join(aliasbase, '.sdk'))
-      search.push(fulltfolder)
-      found = fs.existsSync(fulltfolder)
-    }
-  }
-  else {
-    search.push(fulltfolder)
-    found = fs.existsSync(fulltfolder)
-  }
-
-  if (!found) {
-    throw new Error('Target folder not found in:\n' + search.join('\n  '))
-  }
-
-  // `base` is the target folder relative to the project root. Compare with the
-  // PLATFORM separator: on Windows `root + '/'` never prefixes a normalised
-  // absolute path, so the root would not be stripped and `base` would stay
-  // absolute. Normalise both sides first for the same reason.
-  const nroot = Path.normalize(root)
-  const rootslash = nroot.endsWith(Path.sep) ? nroot : nroot + Path.sep
-  const out = {
-    tname,
-    tfolder: fulltfolder,
-    torigname,
-    base: fulltfolder.startsWith(rootslash)
-      ? fulltfolder.slice(rootslash.length)
-      : fulltfolder
+  return {
+    tname: src.name,
+    tfolder: src.folder,
+    torigname: src.origname,
+    base: src.base,
+    package: src.package,
   }
-
-  return out
 }
 
 
 export {
   action_target,
+  featureCatalogue,
   target_add,
   resolveTarget,
   trimFeatures,
   readTargetFeature,
+  aliasCmpText,
+  aliasCmpName,
+  aliasCmpTree,
+  pruneStaleTemplates,
 }

package/src/cmp/Docs.ts

@@ -0,0 +1,125 @@
+// GENERATING A DOCS ITEM. See docs/design/sdkgen-packages.md §20.3.
+//
+// A docs item is dispatched by the same convention a target is —
+// `cmp/docs/<n>/Main_<n>` — so an item's package supplies the emitter and
+// sdkgen supplies only the call.
+//
+// WHY THIS IS NOT RENDERED BY THE CONSUMER'S Root.ts
+//
+// A project's `Root.ts` is written once, by create-sdkgen, and is never
+// touched again (doctor has an `unwired` category precisely because of it).
+// So a kind introduced later can reach generation in one of two ways: every
+// existing project edits its Root, or sdkgen runs the kind's own pass. The
+// second is what happens here — `docs add` in a project scaffolded years ago
+// generates with no scaffold change at all, which is the whole point of
+// putting the destinations in packages.
+//
+// The cost is honest and small: a second `generate()` call over the same
+// root, so the changes report arrives in two parts.
+
+import { cmp, each, names, Folder } from 'jostraca'
+
+import { requirePath } from '../utility'
+
+import { ensureStdrep } from '../helpers/stdrep'
+
+import { KIT } from '../types'
+
+
+// The model preamble every pass performs before rendering: the case-variant
+// name constants (`Name`, `NAME`, …) and the ProjectName replacement map that
+// template substitution reads.
+//
+// Done HERE rather than relied upon, because a docs pass does NOT go through
+// the consumer's Root — nothing else has set `ctx$.model`, and when there are
+// out-of-tree items the Root was handed a FILTERED COPY, so the preamble it
+// performed did not touch this object at all.
+function prepareModel(model: any, ctx$: any) {
+  ctx$.model = model
+
+  model.const = model.const || { name: model.name }
+  names(model.const, model.name)
+  if (null == model.const.year) {
+    model.const.year = new Date().getFullYear()
+  }
+  names(model, model.name)
+
+  ctx$.stdrep = ctx$.stdrep || {}
+  names(ctx$.stdrep, model.Name, 'Project' + 'Name')
+}
+
+
+// One item: its emitter, called with the item and the shared replace map.
+//
+// No Folder here — WHERE it lands is the caller's business, because that is
+// exactly what differs between the two passes: in-tree the item owns
+// `<sdk-repo>/<name>/`, out-of-tree the destination IS the item's root.
+const DocsItem = cmp(function DocsItem(props: any) {
+  const { item, ctx$ } = props
+  const log = ctx$.log
+  const model = props.model ?? ctx$.model
+
+  const stdrep = ensureStdrep(ctx$)
+
+  // The MODEL KEY is the fallback, and it is not paranoia: `name` comes from
+  // the base schema's `name: key()`, so an item whose project has not
+  // included that schema — or whose own definition omits it — reached
+  // `require('cmp/docs/undefined/Main_undefined')`, a message naming nothing
+  // the author wrote. Seen in the first real install of a docs package.
+  const name = item.name ?? item.key$
+
+  if (null == name || '' === name) {
+    throw new Error(
+      'Docs item has no name and no model key, so its component cannot be ' +
+      'located: ' + JSON.stringify(Object.keys(item ?? {})))
+  }
+
+  const Main_docs = requirePath(ctx$, `cmp/docs/${name}/Main_${name}`)
+
+  Main_docs['Main']({ model, docs: item, stdrep })
+
+  log.info({
+    point: 'generate-docs', docs: name, note: 'docs:' + name
+  })
+})
+
+
+// Every IN-TREE docs item, each in its own folder.
+//
+// Items with `output: path` are excluded: they get their own pass rooted at
+// that path, and rendering them here as well would ALSO write them into
+// `<sdk-repo>/<name>/` — the same reason `withoutExternal` exists for
+// targets.
+const Docs = cmp(function Docs(props: any) {
+  const { ctx$ } = props
+  const model = props.model ?? ctx$.model
+
+  prepareModel(model, ctx$)
+
+  const items = model?.main?.[KIT]?.docs ?? {}
+
+  each(items, (item: any) => {
+    if (false === item.active) {
+      return
+    }
+
+    const path = item.output?.path
+
+    if (null != path && '' !== path) {
+      return
+    }
+
+    const name = item.name ?? item.key$
+
+    names(item, name)
+
+    Folder({ name }, () => DocsItem({ item }))
+  })
+})
+
+
+export {
+  Docs,
+  DocsItem,
+  prepareModel,
+}