@voxgig/create-sdkgen 0.24.0 → 0.26.0

package/src/create-sdkgen.ts

@@ -45,8 +45,6 @@ const { names, Jostraca } = JostracaModule
 const SDK_FOLDER = '.sdk'
 
 
-// TODO: CreateSdkGen opts and generate opts should be mostly the same, and
-// generate should override
 function CreateSdkGen(opts: FullCreateSdkGenOptions) {
   const fs = opts.fs || Fs
 
@@ -107,12 +105,6 @@ function CreateSdkGen(opts: FullCreateSdkGenOptions) {
       folder,
       log: log.child({ cmp: 'jostraca' }),
       meta: { spec },
-      // Overwrite the scaffolded project (.sdk components, templates, build
-      // config) rather than 3-way merge. The scaffold is toolchain-derived and
-      // not hand-edited; merging against a drifting .jostraca base keeps STALE
-      // components/templates on a toolchain bump (so a fix never propagates) and
-      // can inject <<<<<<< markers. See @voxgig/sdkgen
-      // docs/explanation/regeneration-overwrite.md.
       existing: {
         txt: {
           write: true,
@@ -166,7 +158,6 @@ function CreateSdkGen(opts: FullCreateSdkGenOptions) {
 
     projectFolder = Path.resolve(Path.join(__dirname, 'project', spec.project))
 
-    // TODO: support auto install project npm package (specific version) in a special cache folder
 
     if (!fs.existsSync(projectFolder)) {
       projectFolder = spec.project
@@ -275,17 +266,6 @@ async function installNpm(spec: GenerateSpec, opts: any, model: any) {
     await runNpm(['install'], spawn_opts)
   }
 
-  // `-t` / `-f` are INDEPENDENT of `--no-install`: the documented contract is
-  // that --no-install skips `npm install`, not that it drops the requested
-  // targets and features. Adding them is still valid without an install when
-  // the project already has its toolchain (re-scaffolding an existing folder
-  // is a supported flow — "if run against an existing folder generated files
-  // will be overwritten").
-  //
-  // They ARE npm run scripts that resolve @voxgig/sdkgen from node_modules, so
-  // without one they cannot work. Fail with an actionable message rather than
-  // the raw module-resolution error — and rather than silently skipping, which
-  // reports success while leaving config.aon without the requested entries.
   const wanted = [
     (spec.target ?? []).length ? '--target' : '',
     (spec.feature ?? []).length ? '--feature' : '',
@@ -342,21 +322,6 @@ async function installFeatures(spec: GenerateSpec, opts: any, model: any, spawn_
 }
 
 
-/*
-function logfiles(info: any, log: ReturnType<typeof Pino>) {
-  const cwd = process.cwd()
-
-    ; Object.keys(info.files).map(action => {
-      let entries = info.files[action]
-      if (0 < entries.length) {
-        log.debug({
-          point: 'file-' + action, entries,
-          note: '\n' + entries.map((n: any) => n.replace(cwd, '.')).join('\n')
-        })
-      }
-    })
-}
-*/
 
 export type {
   CreateSdkGenOptions,

package/src/project/standard/CreateRoot.ts

@@ -1,7 +1,6 @@
 
 
 import Path from 'node:path'
-// import * as Fs from 'node:fs'
 
 import {
   names,
@@ -62,39 +61,6 @@ log/
 `
 
 
-// The guide overlay is the ONE model file the user owns.
-//
-// Everything else the scaffold writes is toolchain-derived and is deliberately
-// OVERWRITTEN (see the `existing.txt.write` rationale in create-sdkgen.ts) so a
-// toolchain fix propagates. `model/guide/guide.aon` is the exception: apidef
-// unifies it OVER the heuristic classification, and it is where every
-// documented customization lives — entity rename, hide, move, activate,
-// per-path deactivation, method override, param rename, response transform.
-// Copying the stub over it destroyed that work on every re-scaffold, and
-// cedar-regen.sh re-scaffolds on every regen, so the loss was silent and
-// repeated.
-//
-// It is excluded from the bulk Copy and merged instead (see mergeGuide).
-// The PROJECT overlay: the second model file the user owns.
-//
-// `guide.aon` owns what the API looks like. This owns what the PROJECT is —
-// publication values above all. The sdkgen schema tells you to declare those
-// in `model/sdk.aon` "where they survive a resync", and that was simply not
-// true: ModelSdk rewrites sdk.aon from its template on every scaffold, so a
-// version or package name declared there vanished before the model was built,
-// with no error. The cedar fleet ran for months with every manifest pinned at
-// the schema default 0.0.1 while its git tags climbed past 0.1.1, and this is
-// why.
-//
-// sdk.aon cannot simply be merged the way guide.aon is. Its template owns
-// `name`, `origin` and especially `def` — the OpenAPI filename, which really
-// does change (three cedar specs were renamed in one week). A "keep the user's
-// file" merge would freeze `def` at a spec that no longer exists and break
-// regeneration. So the template keeps sole ownership of sdk.aon, and the
-// user gets a file of their own that sdk.aon includes.
-//
-// Written ONCE. If it exists, it is re-emitted byte-for-byte, so a
-// re-scaffold is a no-op on it.
 const PROJECT_FILE = 'project.aon'
 const PROJECT_STUB = `# Project overlay — YOURS. The scaffold creates this file once and never
 # overwrites it, unlike every other file it writes.
@@ -127,17 +93,6 @@ const GUIDE_FILE = 'guide.aon'
 const GUIDE_REL = ['model', 'guide', GUIDE_FILE]
 
 
-// Rename a user-owned overlay from its pre-2026-08 `.aontu` name to `.aon`.
-//
-// Both overlays are read-if-present and written-if-absent, which is exactly
-// the shape that turns an extension rename into DATA LOSS rather than a
-// rename: look for `guide.aon`, find nothing, write a fresh template over the
-// top, and the user's entity renames, hides and overrides are still sitting
-// in `guide.aontu` being ignored. 660 generated repos carry one.
-//
-// So the legacy file is moved to the new name BEFORE anything reads or writes
-// it. Contents are untouched; only the name changes. Idempotent — once the
-// `.aon` exists this does nothing, so a re-scaffold stays a no-op.
 function migrateOverlay(fs: any, dir: string, name: string): void {
   const next = Path.join(dir, name + '.aon')
   const prev = Path.join(dir, name + '.aontu')
@@ -145,15 +100,6 @@ function migrateOverlay(fs: any, dir: string, name: string): void {
     return
   }
   try {
-    // RENAME THE FILE *AND* ITS INCLUDES. An overlay written before the
-    // rename includes the toolchain schemas by their old names —
-    // `@"@voxgig/apidef/model/guide.aontu"` — and apidef 8 no longer ships
-    // that file, so a migration that moved the file but kept its contents
-    // verbatim produced a project that could not resolve its own guide.
-    // mergeGuide cannot repair this either: it keeps the user's lines and
-    // only ADDS missing template includes, so the dead one would survive
-    // beside the new one. Only `@`-include extensions are touched; nothing
-    // else in the user's file is rewritten.
     const src = String(fs.readFileSync(prev))
       .replace(/(@['"][^'"]+)\.aontu(['"])/g, '$1.aon$2')
     fs.writeFileSync(next, src)
@@ -166,17 +112,6 @@ function migrateOverlay(fs: any, dir: string, name: string): void {
 }
 
 
-// Merge the guide template into an existing guide overlay.
-//
-// A guide is the template's `@`-includes plus whatever the user added. The
-// includes are the only part the template OWNS, so the merge is: keep the
-// user's file verbatim, and restore any include it is missing. When nothing
-// is missing — the normal case — the file is returned byte-identical, so a
-// re-scaffold is a no-op on it.
-//
-// Missing includes are restored at the TOP, not appended: `base-guide.aon`
-// carries the heuristic classification that the user's overrides unify over,
-// and the overlay reads correctly only when the includes precede it.
 function mergeGuide(existing: string | null, template: string): string {
   if (null == existing) {
     return template
@@ -184,18 +119,6 @@ function mergeGuide(existing: string | null, template: string): string {
 
   const isInclude = (line: string) => line.trim().startsWith('@')
 
-  // AN INCLUDE IS THE FILE IT NAMES, whichever way the `./` falls.
-  //
-  // The template gained a `./` when aontu 0.65 made a bare single-segment
-  // include name a PACKAGE (ADR-039). Every guide written before that says
-  // `@"base-guide.aon"`, and `guide.aon` is project-owned: the scaffold
-  // writes it once and never again, so those files stay as they are until
-  // something migrates them.
-  //
-  // Comparing the raw lines read the old spelling as a DIFFERENT include, so
-  // a re-scaffold restored one the file already had — leaving the guide
-  // including `base-guide.aon` twice, under two spellings, which is the one
-  // thing this merge exists to avoid.
   const key = (line: string) => line.trim().replace(/^@"\.\//, '@"')
 
   const have = new Set(existing.split('\n').map(key))
@@ -212,26 +135,10 @@ function mergeGuide(existing: string | null, template: string): string {
 }
 
 
-// The OpenAPI filename is inherited from the upstream API slug, and upstream
-// slugs are not constrained: the freepublicapis corpus contains apostrophes
-// (catherine-shulman's-quotes), accents (dólar-y-monedas, kölner-adressen),
-// and '!' / '>' / '_'. That name is copied into .sdk/def/ AND written verbatim
-// into a single-quoted aontu string in sdk.aon:
-//
-//     def: 'catherine-shulman's-quotes_0.1.0.json'
-//                              ^ terminates the string -> AontuError, no SDK
-//
-// Slugs are [a-z0-9-]; a filename additionally needs '.' and '_' for the
-// version segment and extension, so those are kept — which also means every
-// already-conforming name (including cedar's dotted gitlab-v4-swagger-2.0.yaml)
-// is untouched and no repo churns. Everything else is folded to '-'.
 function sanitizeDefName(filename: string): string {
   const clean = filename
-    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')  // dólar -> dolar
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
     .toLowerCase()
-    // Quotes are ELIDED, not folded to '-', so the filename agrees with the
-    // repo name apidef's sanitizeSlug derives from the same slug:
-    // catherine-shulman's-quotes -> catherine-shulmans-quotes(-sdk).
     .replace(/['’"]/g, '')
     .replace(/[^a-z0-9._-]+/g, '-')
     .replace(/-+/g, '-')
@@ -244,17 +151,13 @@ function sanitizeDefName(filename: string): string {
 }
 
 
-// TODO: rename to RootSdk
 const CreateRoot = cmp(function CreateRoot(props: any) {
   const { ctx$, ctx$: { folder }, spec, model } = props
   const fs = ctx$.fs()
 
-  // TODO: move to @voxgig/util as duplicated
   model.const = { name: model.name }
   names(model.const, model.name)
   model.const.year = new Date().getFullYear()
-  // Scaffold is MIT-licensed (matches the emitted LICENSE and tm/LICENSE);
-  // set directly rather than via names() so the value stays 'MIT', not 'Mit'.
   model.const.License = 'MIT'
 
   ctx$.model = model
@@ -263,11 +166,7 @@ const CreateRoot = cmp(function CreateRoot(props: any) {
     const from =
       Path.resolve(Path.join(__dirname, '..', '..', '..', 'project', 'standard'))
 
-    // console.log('FROM', from)
 
-    // Copy `exclude` matches the SOURCE-RELATIVE path exactly, so this names
-    // the one guide under the scaffold and nothing else. It is re-emitted,
-    // merged, in the model folder below.
     const guideExclude = [spec.sdk_folder, ...GUIDE_REL].join('/')
 
     Copy({
@@ -296,7 +195,6 @@ const CreateRoot = cmp(function CreateRoot(props: any) {
       })
 
       Folder({ name: 'def' }, () => {
-        // TODO: file existence check should be jostraca util
         if (fs.existsSync(origdef)) {
           Copy({ from: origdef, to: projdef })
         }