@voxgig/apidef 8.15.1 → 8.16.0

package/src/guide/guide.ts

@@ -2,7 +2,7 @@
 
 import Path from 'node:path'
 
-import { Jostraca, Project, File, Content, each } from 'jostraca'
+import { each } from 'jostraca'
 
 import { Aontu } from 'aontu'
 
@@ -46,47 +46,79 @@ const aontu = new Aontu()
 
 
 
-function migrateLegacyGuide(fs: any, folder: string, guideprefix: string): boolean {
-  const guidepath = Path.join(folder, 'guide', guideprefix + 'guide.aon')
-  const legacyguide = Path.join(folder, 'guide', guideprefix + 'guide.aontu')
-
-  if (fs.existsSync(guidepath) || !fs.existsSync(legacyguide)) {
-    return false
-  }
-
-  let migrated = String(fs.readFileSync(legacyguide, 'utf8'))
-    .replace(/@"@voxgig\/apidef\/model\/guide\.aontu"/g,
-      '@"@voxgig/apidef/model/guide.aon"')
+function migrateGuideIncludes(src: string, guideprefix: string): string {
+  let migrated = src
+    .replace(/@"@voxgig\/apidef\/model\/guide\.aon"/g,
+      '@"@voxgig/apidef/model/guide.aontu"')
 
   // The sibling include is written bare or with `./`; both name this file.
   for (const dir of ['', './']) {
     migrated = migrated
-      .split('@"' + dir + guideprefix + 'base-guide.aontu"')
-      .join('@"' + dir + guideprefix + 'base-guide.aon"')
+      .split('@"' + dir + guideprefix + 'base-guide.aon"')
+      .join('@"' + dir + guideprefix + 'base-guide.aontu"')
   }
 
-  fs.writeFileSync(guidepath, migrated)
+  return migrated
+}
+
+
+// aontu refuses a bare sibling include, so it gains the `./` it needs.
+function prefixGuideInclude(src: string, guideprefix: string): string {
+  return src
+    .split('@"' + guideprefix + 'base-guide.aontu"')
+    .join('@"./' + guideprefix + 'base-guide.aontu"')
+}
+
+
+// A `.aon` entry file is unresolvable: aontu reads only `.aontu` as source.
+// So this renames AND rewrites both includes — a repair, not a convenience.
+function migrateLegacyGuide(fs: any, folder: string, guideprefix: string): boolean {
+  const guidepath = Path.join(folder, 'guide', guideprefix + 'guide.aontu')
+  const legacyguide = Path.join(folder, 'guide', guideprefix + 'guide.aon')
+
+  if (fs.existsSync(guidepath) || !fs.existsSync(legacyguide)) {
+    return false
+  }
+
+  fs.writeFileSync(guidepath,
+    migrateGuideIncludes(String(fs.readFileSync(legacyguide, 'utf8')), guideprefix))
   try { fs.unlinkSync(legacyguide) } catch (_err: any) { }
 
   return true
 }
 
+
+// A `.aontu` entry file may still include a `.aon` sibling, so the rename
+// above never fires for it while its include still names an absent file.
+function migrateLegacyGuideInclude(
+  fs: any, guidepath: string, guideprefix: string
+): boolean {
+  return rewriteGuide(fs, guidepath, (src) => migrateGuideIncludes(src, guideprefix))
+}
+
+
 function migrateGuideIncludePrefix(
   fs: any, guidepath: string, guideprefix: string
+): boolean {
+  return rewriteGuide(fs, guidepath, (src) => prefixGuideInclude(src, guideprefix))
+}
+
+
+function rewriteGuide(
+  fs: any, guidepath: string, rewrite: (src: string) => string
 ): boolean {
   if (!fs.existsSync(guidepath)) {
     return false
   }
 
-  const bare = '@"' + guideprefix + 'base-guide.aon"'
   const src = String(fs.readFileSync(guidepath, 'utf8'))
+  const migrated = rewrite(src)
 
-  if (!src.includes(bare)) {
+  if (migrated === src) {
     return false
   }
 
-  fs.writeFileSync(guidepath,
-    src.split(bare).join('@"./' + guideprefix + 'base-guide.aon"'))
+  fs.writeFileSync(guidepath, migrated)
 
   return true
 }
@@ -94,6 +126,26 @@ function migrateGuideIncludePrefix(
 
 
 
+function guideConflictMessage(
+  path: string, conflict: { line: number, text: string }
+): string {
+  return `@voxgig/apidef: guide: unresolved merge conflict at ${path}:${conflict.line}\n` +
+    `  ${conflict.text}\n` +
+    `Resolve the marked block in ${path}.`
+}
+
+
+function missingGuideMessage(path: string, guideprefix: string): string {
+  return `@voxgig/apidef: guide: ${path} defines no guide map; it needs the include ` +
+    `@"./${guideprefix}base-guide.aontu".`
+}
+
+
+function isPlainObject(val: any): boolean {
+  return null != val && 'object' === typeof val && !Array.isArray(val)
+}
+
+
 function findConflict(src: string): { line: number, text: string } | null {
   const lines = String(src || '').split('\n')
 
@@ -115,7 +167,7 @@ async function buildGuide(ctx: ApiDefContext): Promise<any> {
   const folder = Path.resolve(ctx.opts.folder)
 
   try {
-    const basejres = await buildBaseGuide(ctx)
+    await buildBaseGuide(ctx)
   }
   catch (err: any) {
     errs.push(err)
@@ -125,16 +177,23 @@ async function buildGuide(ctx: ApiDefContext): Promise<any> {
 
   let src = ''
   const guideprefix = null == ctx.opts.outprefix ? '' : ctx.opts.outprefix
-  let guidepath = Path.join(folder, 'guide', guideprefix + 'guide.aon')
+  let guidepath = Path.join(folder, 'guide', guideprefix + 'guide.aontu')
 
   if (migrateLegacyGuide(ctx.fs, folder, guideprefix)) {
-    log.info({ point: 'migrate-guide', note: 'guide.aontu -> guide.aon' })
+    log.info({ point: 'migrate-guide', note: 'guide.aon -> guide.aontu' })
+  }
+
+  if (migrateLegacyGuideInclude(ctx.fs, guidepath, guideprefix)) {
+    log.info({
+      point: 'migrate-guide-include',
+      note: 'base-guide.aon -> base-guide.aontu'
+    })
   }
 
   if (migrateGuideIncludePrefix(ctx.fs, guidepath, guideprefix)) {
     log.info({
       point: 'migrate-guide-prefix',
-      note: 'base-guide.aon -> ./base-guide.aon'
+      note: 'base-guide.aontu -> ./base-guide.aontu'
     })
   }
 
@@ -154,35 +213,10 @@ async function buildGuide(ctx: ApiDefContext): Promise<any> {
 
   handleErrors(ctx, errs)
 
-  const basepath = Path.join(folder, 'guide', guideprefix + 'base-guide.aon')
-  for (const checkpath of [guidepath, basepath]) {
-    let checksrc = ''
-    try {
-      checksrc = checkpath === guidepath ? src : String(ctx.fs.readFileSync(checkpath, 'utf8'))
-    }
-    catch (_err: any) {
-      continue
-    }
-
-    const conflict = findConflict(checksrc)
-    if (null != conflict) {
-      errs.push(new Error(
-        `@voxgig/apidef: guide: unresolved merge conflict at ${
-          relativizePath(checkpath)}:${conflict.line}\n` +
-        `  ${conflict.text}\n` +
-        `A guide is merged, not overwritten, so an edit the regenerated base\n` +
-        `guide contradicts is left for a human to settle. Resolve the marked\n` +
-        `block` +
-        // DELETING ONLY HELPS FOR THE BASE GUIDE. Regeneration rewrites that
-        // file, while the top-level entry guide is the user's own and is read
-        // back unchanged — so advising its deletion would send a reader in a
-        // circle, failing this same check on the next build.
-        (checkpath === basepath ?
-          `, or delete ${guideprefix}base-guide.aon to regenerate it from the\n` +
-          `specification and re-apply the edit afterwards.` :
-          ` in ${relativizePath(checkpath)}.`)))
-      break
-    }
+  // Only the entry file: the base guide was just rewritten from the spec.
+  const conflict = findConflict(src)
+  if (null != conflict) {
+    errs.push(new Error(guideConflictMessage(relativizePath(guidepath), conflict)))
   }
 
   handleErrors(ctx, errs)
@@ -194,7 +228,7 @@ async function buildGuide(ctx: ApiDefContext): Promise<any> {
 
     const opts: any = {
       path: guidepath,
-      errs,
+      errfs: ctx.fs,
     }
 
     if (ctx.fsInjected) {
@@ -203,7 +237,19 @@ async function buildGuide(ctx: ApiDefContext): Promise<any> {
 
     ctx.work.guideAontuFs = undefined !== opts.fs
 
-    const guideModel = aontu.generate(src, opts)
+    // One AontuError carries every aontu failure, formatted: collect mode
+    // leaves a generation-time failure's message empty.
+    let guideModel: any
+    try {
+      guideModel = aontu.generate(src, opts)
+    }
+    catch (err: any) {
+      errs.push(err)
+    }
+
+    if (0 === errs.length && !isPlainObject(guideModel?.guide)) {
+      errs.push(new Error(missingGuideMessage(relativizePath(guidepath), guideprefix)))
+    }
 
     handleErrors(ctx, errs)
 
@@ -256,8 +302,10 @@ async function buildBaseGuide(ctx: ApiDefContext) {
     throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
   }
 
+  const guideprefix = null == ctx.opts.outprefix ? '' : ctx.opts.outprefix
+
   const guideBlocks = [
-    '# Guide',
+    ...baseGuideHeader(guideprefix),
     '',
     'guide: {',
   ]
@@ -371,7 +419,7 @@ async function buildBaseGuide(ctx: ApiDefContext) {
       guideBlocks.push(
         `    # Deactivated by the heuristic` +
         (null == why ? '' : ` (${why})`) + `. Set` +
-        ` \`active: true\` here in guide.aon to generate it as an entity.`)
+        ` \`active: true\` here in guide.aontu to generate it as an entity.`)
       guideBlocks.push(`    active: *false`)
     }
 
@@ -392,25 +440,32 @@ async function buildBaseGuide(ctx: ApiDefContext) {
 
   ctx.note.guide = { base: guideSrc }
 
-  const baseGuideFileName =
-    (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'base-guide.aon'
+  const guidefolder = Path.join(ctx.opts.folder, 'guide')
+  ctx.fs.mkdirSync(guidefolder, { recursive: true })
+  ctx.fs.writeFileSync(Path.join(guidefolder, guideprefix + 'base-guide.aontu'), guideSrc)
+}
 
-  const jostraca = Jostraca({
-    folder: ctx.opts.folder + '/guide',
-    now: ctx.spec.now,
-    fs: () => ctx.fs,
-    log: ctx.log,
-  })
 
-  const root = () => Project({ folder: '.' }, async () => {
-    File({ name: baseGuideFileName }, () => Content(guideSrc))
-  })
+// The entry file a project writes once and owns; the CLI prints it.
+function guideEntrySource(guideprefix: string): string[] {
+  return [
+    '# Guide entry file: put customizations below the includes. The base guide',
+    '# it includes is generated and overwritten on every build.',
+    '@"@voxgig/apidef/model/guide.aontu"',
+    '@"./' + guideprefix + 'base-guide.aontu"',
+  ]
+}
 
-  const jres = await jostraca.generate({
-    existing: { txt: { merge: true } }
-  }, root)
 
-  return jres
+// Written into every base guide, so a reader of the file learns where an
+// edit belongs before making one there.
+function baseGuideHeader(guideprefix: string): string[] {
+  return [
+    '# Generated from the API definition and overwritten on every build: do not',
+    '# edit this file. Put customizations in the guide entry file, which includes',
+    '# this one and overrides its defaults:',
+    '#   ' + guideprefix + 'guide.aontu',
+  ]
 }
 
 
@@ -555,6 +610,13 @@ function validateBaseBuide(ctx: ApiDefContext, baseguide: any) {
 
 
 export {
+  migrateGuideIncludes,
+  prefixGuideInclude,
+  findConflict,
+  guideConflictMessage,
+  missingGuideMessage,
+  baseGuideHeader,
+  guideEntrySource,
   migrateLegacyGuide,
   migrateGuideIncludePrefix,
   buildGuide

package/src/guide/heuristic01.ts

@@ -8,7 +8,7 @@ import { each } from 'jostraca'
 import { size, merge, getelem, isempty, items, keysof } from '@voxgig/struct'
 
 import {
-  isEntityWrapperProp, envelopeProp, closedBodyTransform,
+  isEntityWrapperProp, envelopeProp, envelopeItemRef, closedBodyTransform,
   authExchangeOp, specSecuredByDefault,
 } from '../utility'
 
@@ -66,6 +66,8 @@ import { snakify } from 'jostraca'
 
 import { mergeCollectionPaths } from '../transform/entity'
 
+import { byCodePoint, countRefs, satAdd } from '../refcount'
+
 import type {
   PathMatch
 } from '../utility'
@@ -77,8 +79,8 @@ const KONSOLE_LOG = console['log']
 // Log non - fatal wierdness.
 const dlog = getdlog('apidef', __filename)
 
-// Schema components that occur less than this rate(over total method count) qualify
-// as unique entities, not shared schemas
+// A schema whose per-use occurrences, over the method count or over the path
+// count, fall below these rates names an entity rather than a shared shape.
 const IS_ENTCMP_METHOD_RATE = 0.21
 const IS_ENTCMP_PATH_RATE = 0.41
 
@@ -98,6 +100,9 @@ const METHOD_IDOP: Record<string, string> = {
   OPTIONS: 'OPTIONS',
 }
 
+// Tried in order: the first shape a path matches decides how its entity is named.
+const ENTITY_PATH_SHAPES = ['t/p/t/', 't/p/', 'p/t/', 't/', 't/p/p']
+
 const METHOD_CONSIDER_ORDER: Record<string, number> = {
   'GET': 100,
   'QUERY': 150,
@@ -123,6 +128,8 @@ async function heuristic01(ctx: ApiDefContext): Promise<Guide> {
       ]
     },
     { select: selectCmpXrefs, apply: MeasureRef },
+    { select: selectAllMethods, apply: MeasureEnvelope },
+    MeasureEnvelopeItems,
     {
       select: selectAllMethods, apply: [
         ResolveEntityComponent,
@@ -206,6 +213,7 @@ function Prepare(spec: TaskSpec) {
     work: {
       pathmap: {},
       entmap: {},
+      envelope: {},
       entity: {
         count: {
           seen: 0,
@@ -279,10 +287,11 @@ function PreparePath(spec: TaskSpec) {
 
 
 function selectCmpXrefs(_source: any, spec: TaskSpec) {
-  const out = find(spec.ctx.def, 'x-ref')
-    .filter(xref => xref.val.match(/\/(components\/schemas|definitions)\//))
-
-  return out
+  const counts = countRefs(spec.ctx.def)
+  return Object.keys(counts)
+    .sort(byCodePoint)
+    .filter(val => val.match(/\/(components\/schemas|definitions)\//))
+    .map(val => ({ val, count: counts[val] }))
 }
 
 
@@ -290,14 +299,16 @@ function MeasureRef(spec: TaskSpec) {
   const guide = spec.data.guide
   const metrics = guide.metrics
 
-  let m = spec.node.val.val.match(/\/(components\/schemas|definitions)\/(.+)$/)
+  const xref = spec.node.val
+  let m = xref.val.match(/\/(components\/schemas|definitions)\/(.+)$/)
   if (m) {
     const name = canonizeCmpName(m[2])
     if (null == metrics.count.origcmprefs[name]) {
       metrics.count.cmp++
       metrics.count.origcmprefs[name] = 0
     }
-    metrics.count.origcmprefs[name]++
+    metrics.count.origcmprefs[name] =
+      satAdd(metrics.count.origcmprefs[name], xref.count)
 
     if (null == metrics.found.cmp[name]) {
       metrics.found.cmp[name] = { orig: m[2] }
@@ -306,6 +317,44 @@ function MeasureRef(spec: TaskSpec) {
 }
 
 
+// Being an envelope belongs to the component, not to one operation: it names
+// through the record it carries only when every operation answering with it
+// unwraps it, so the operations on one resource are never split between the
+// record's name and the envelope's. An operation unwraps only the response
+// ResolveTransform reads. The entry is the item's reference, or '' for none.
+function MeasureEnvelope(spec: TaskSpec) {
+  const work = spec.data.work
+  const mdesc = spec.node.val
+  const opname = methodOpname(mdesc, matchEntityPath(work.pathmap[mdesc.path].parts), [])
+  const unwrapref = getResponseSchema(successResponse(mdesc.responses))?.['x-ref']
+
+  for (const schema of successSchemas(mdesc.responses)) {
+    const xref = schema['x-ref']
+    if (null != xref) {
+      const itemref = null == opname || xref !== unwrapref ? null :
+        envelopeItemRef(schema, opname)
+      work.envelope[xref] = '' === work.envelope[xref] || null == itemref ? '' : itemref
+    }
+  }
+}
+
+
+// An item carried by more than one envelope is named by none of them: the
+// envelopes' own names are then what tell the resources apart.
+function MeasureEnvelopeItems(spec: TaskSpec) {
+  const envelope: Record<string, string> = spec.data.work.envelope
+  const carriers: Record<string, number> = {}
+  for (const itemref of Object.values(envelope)) {
+    carriers[itemref] = (carriers[itemref] ?? 0) + 1
+  }
+  for (const xref of Object.keys(envelope)) {
+    if (1 < carriers[envelope[xref]]) {
+      envelope[xref] = ''
+    }
+  }
+}
+
+
 function selectAllMethods(_source: any, spec: TaskSpec): MethodDesc[] {
   const ctx = spec.ctx
 
@@ -370,9 +419,10 @@ function ResolveEntityComponent(spec: TaskSpec) {
 
   let responses = methodDef.responses
 
-  let origxrefs: any[] = findPotentialSchemaRefs(pathStr, methodName, responses).map(val => ({
-    val
-  }))
+  let origxrefs: any[] = findPotentialSchemaRefs(
+    pathStr, methodName, responses, work.envelope, why_cmp).map(val => ({
+      val
+    }))
 
   let cmpxrefs = origxrefs
     .filter(xref => xref.val.includes('schema') || xref.val.includes('definitions'))
@@ -544,25 +594,25 @@ function ResolveEntityName(spec: TaskSpec) {
 
   let entname
 
-  let pm = undefined
+  const pm = matchEntityPath(parts)
 
-  if (pm = pathMatch(parts, 't/p/t/')) {
+  if ('t/p/t/' === pm?.expr) {
     entname = entityPathMatch_tpte(data, pm, mdesc, why_path)
   }
 
-  else if (pm = pathMatch(parts, 't/p/')) {
+  else if ('t/p/' === pm?.expr) {
     entname = entityPathMatch_tpe(data, pm, mdesc, why_path)
   }
 
-  else if (pm = pathMatch(parts, 'p/t/')) {
+  else if ('p/t/' === pm?.expr) {
     entname = entityPathMatch_pte(data, pm, mdesc, why_path)
   }
 
-  else if (pm = pathMatch(parts, 't/')) {
+  else if ('t/' === pm?.expr) {
     entname = entityPathMatch_te(data, pm, mdesc, why_path)
   }
 
-  else if (pm = pathMatch(parts, 't/p/p')) {
+  else if ('t/p/p' === pm?.expr) {
     entname = entityPathMatch_tpp(data, pm, mdesc, why_path)
   }
 
@@ -1004,7 +1054,7 @@ function ResolveOperation(spec: TaskSpec) {
 
 
   if ('load' === standard_opname) {
-    const islist = isListResponse(mdesc, pathStr, why_op)
+    const islist = isListResponse(mdesc, ment.pm, pathStr, why_op)
     opname = islist ? 'list' : opname
   }
 
@@ -1074,8 +1124,7 @@ function ResolveTransform(spec: TaskSpec) {
     res: undefined,
   }
 
-  const resokdef = mdesc.responses?.[200] || mdesc.responses?.[201]
-  const resprops = getResponseSchema(resokdef)?.properties
+  const resprops = getResponseSchema(successResponse(mdesc.responses))?.properties
   debugpath(pathStr, methodName, 'TRANSFORM-RES', keysof(resprops))
 
   if (resprops) {
@@ -1418,6 +1467,21 @@ function getRequestBodySchema(requestBody: any) {
     requestBody?.schema
 }
 
+// The response an operation's result is read from.
+function successResponse(responses: any): any {
+  return responses?.[200] ?? responses?.[201]
+}
+
+
+// The response schemas an operation answers with when it succeeds, in the
+// order they are tried.
+function successSchemas(responses: any): any[] {
+  return ['200', '201']
+    .map((rescode) => getResponseSchema(responses?.[rescode]))
+    .filter((schema) => null != schema)
+}
+
+
 function getResponseSchema(response: any) {
   return response?.content?.['application/json']?.schema ??
     response?.schema
@@ -1634,14 +1698,35 @@ function cmpOccursInPath(data: { def: any, work: any }, cmpname: string): boolea
 
 
 
+function matchEntityPath(parts: string[]): PathMatch | null {
+  for (const shape of ENTITY_PATH_SHAPES) {
+    const pm = pathMatch(parts, shape)
+    if (null != pm) {
+      return pm
+    }
+  }
+  return null
+}
+
+
+// The operation ResolveOperation will assign, needed before the entity is
+// named: whether a response unwraps as an envelope depends on it.
+function methodOpname(
+  mdesc: Record<string, any>,
+  pm: PathMatch | null,
+  why: string[]
+): string | undefined {
+  const opname = METHOD_IDOP[mdesc.method]
+  return 'load' === opname && isListResponse(mdesc, pm, mdesc.path, why) ? 'list' : opname
+}
+
+
 function isListResponse(
   mdesc: Record<string, any>,
+  pm: PathMatch | null | undefined,
   pathStr: string,
   why: string[]
 ): boolean {
-  const ment = mdesc.MethodEntity
-  const pm = ment.pm
-
   let islist = false
   let schema
 
@@ -1652,8 +1737,7 @@ function isListResponse(
     why.push('end-param')
   }
   else {
-    const response = mdesc.responses?.[200] ?? mdesc.responses?.[201]
-    schema = getResponseSchema(response)
+    schema = getResponseSchema(successResponse(mdesc.responses))
 
     if (null == schema) {
       why.push('no-schema')
@@ -1875,22 +1959,30 @@ function makeMethodEntityDesc(desc: Record<string, any>): MethodEntityDesc {
 }
 
 
-function findPotentialSchemaRefs(pathStr: string, methodName: string, responses: any) {
+function findPotentialSchemaRefs(
+  pathStr: string,
+  methodName: string,
+  responses: any,
+  envelope: Record<string, string>,
+  why: string[],
+) {
   const xrefs: string[] = []
-  if (null == responses) {
-    return xrefs
-  }
-  const rescodes = ['200', '201']
-  for (let rescode of rescodes) {
-    const schema = getResponseSchema(responses[rescode])
-    if (null != schema) {
-      if (null != schema['x-ref']) {
-        xrefs.push(schema['x-ref'])
+  for (const schema of successSchemas(responses)) {
+    if (null != schema['x-ref']) {
+      // An envelope component names its wrapping, not the entity: the
+      // component it carries takes its place.
+      const itemref = envelope[schema['x-ref']]
+      if ('' !== itemref) {
+        why.push('envelope=' + cmpRefName(schema['x-ref']))
+        xrefs.push(itemref)
       }
-      else if ('array' === schema.type && null != schema.items?.['x-ref']) {
-        xrefs.push(schema.items?.['x-ref'])
+      else {
+        xrefs.push(schema['x-ref'])
       }
     }
+    else if ('array' === schema.type && null != schema.items?.['x-ref']) {
+      xrefs.push(schema.items?.['x-ref'])
+    }
   }
 
   debugpath(pathStr, methodName, 'POTENTIAL-SCHEMA-REFS', xrefs)
@@ -1898,6 +1990,12 @@ function findPotentialSchemaRefs(pathStr: string, methodName: string, responses:
 }
 
 
+function cmpRefName(xref: string): string {
+  const m = xref.match(/\/(components\/schemas|definitions)\/(.+)$/)
+  return null == m ? xref : canonizeCmpName(m[2])
+}
+
+
 function hasMethod(def: any, pathStr: string, methodName: string) {
   const pathDef = def?.paths?.[pathStr]
   const found = (