@voxgig/apidef 8.11.0 → 8.12.1

package/src/apidef.ts

@@ -75,10 +75,17 @@ import { graphqlTransform } from './transform/graphql'
 import { argsTransform } from './transform/args'
 import { selectTransform } from './transform/select'
 import { fieldTransform } from './transform/field'
+import { casecollideTransform } from './transform/casecollide'
 import { flowTransform } from './transform/flow'
 import { flowstepTransform } from './transform/flowstep'
 import { cleanTransform } from './transform/clean'
 
+import {
+  publishResolved, operationFacts, operationIndex, resolvedSpec,
+} from './resolved'
+
+import type { OperationFacts, ResolvedSpec } from './resolved'
+
 import { makeEntityBuilder } from './builder/entity'
 import { gcEntityFiles } from './builder/entity/entity'
 import { makeFlowBuilder } from './builder/flow'
@@ -87,18 +94,6 @@ import { makeFlowBuilder } from './builder/flow'
 const dlog = getdlog('apidef', __filename)
 
 
-// THE WARNINGS FILE IS A REVIEWABLE ARTIFACT, so it carries no clock.
-//
-// Every warning is stamped with `when: Date.now()` — useful in a live log,
-// and fatal in a file that consumers COMMIT. An SDK project regenerates and
-// commits `.sdk/apidef-warnings.txt`, and its CI asserts that a regeneration
-// reproduces the committed tree byte for byte; with a timestamp in it that
-// check can never pass, and every regeneration produces a diff saying
-// nothing about the warnings themselves. github-sdk failed exactly that way:
-// one file, three changed lines, all of them clocks.
-//
-// The timestamp stays on the in-memory history, where a caller streaming
-// warnings still wants it.
 function warningsFileText(history: any[]): string {
   return history
     .map((n: any) => {
@@ -111,7 +106,6 @@ function warningsFileText(history: any[]): string {
 
 function ApiDef(opts: ApiDefOptions) {
 
-  // TODO: shape opts!
   const fs = opts.fs || Fs
   const pino = prettyPino('apidef', opts)
   const log = pino.child({ cmp: 'apidef' })
@@ -173,7 +167,6 @@ function ApiDef(opts: ApiDefOptions) {
         start
       })
 
-      // TODO: Validate spec
       ctx = {
         fs,
         fsInjected: null != opts.fs,
@@ -189,7 +182,6 @@ function ApiDef(opts: ApiDefOptions) {
         note: {},
         warn,
 
-        // TODO: remove (moved to guide)
         metrics: {
           count: {
             path: 0,
@@ -235,6 +227,7 @@ function ApiDef(opts: ApiDefOptions) {
       }
 
       ctx.def = def
+      ctx.resolved = publishResolved(spec.buildctx, spec.config?.kind ?? "openapi3", def)
 
       steps.push('parse')
 
@@ -276,6 +269,8 @@ function ApiDef(opts: ApiDefOptions) {
       await argsTransform(ctx)
       await selectTransform(ctx)
       await fieldTransform(ctx)
+      // Before flowTransform, so no flow is built for an entity it drops.
+      await casecollideTransform(ctx)
       await flowTransform(ctx)
       await flowstepTransform(ctx)
       await cleanTransform(ctx)
@@ -293,7 +288,6 @@ function ApiDef(opts: ApiDefOptions) {
       const builders = [
         await makeEntityBuilder(ctx),
 
-        // TODO: move to sdkgen
         await makeFlowBuilder(ctx),
       ]
 
@@ -326,11 +320,6 @@ function ApiDef(opts: ApiDefOptions) {
         // folder: Path.dirname(opts.folder as string),
         folder: opts.folder,
         model: jmodel,
-        // Overwrite the generated model source (.aontu) rather than 3-way merge:
-        // merging against a drifting .jostraca base silently keeps stale files
-        // and can inject <<<<<<< conflict markers. Generated output is
-        // model-derived and never hand-edited. See sdkgen
-        // docs/explanation/regeneration-overwrite.md.
         existing: { txt: { write: true, merge: false } }
       }, root)
 
@@ -343,11 +332,6 @@ function ApiDef(opts: ApiDefOptions) {
 
       steps.push('generate')
 
-      // Garbage-collect entity model files no longer derived from the def.
-      // The builders only ever WRITE: a spec change that removes or renames a
-      // derived entity used to leave the old <name>.aontu behind forever.
-      // Runs after generate so the current set is on disk; guarded so only
-      // apidef-generated files under this build's outprefix are touched.
       try {
         const kitEntity = (ctx.apimodel?.main as any)?.[KIT]?.entity || {}
         gcEntityFiles(fs, log, opts.folder as string, opts.outprefix,
@@ -368,12 +352,6 @@ function ApiDef(opts: ApiDefOptions) {
           warningsFileText(warn.history))
       }
 
-      // apidef writes model source files (entity, flow, guide aontu files) into
-      // .sdk/model/. Downstream actions (sdkgen, etc.) read those via
-      // sdk.aontu @-includes, so voxgig-model has to re-resolve the model
-      // before the post-step actions run. Signal reload whenever jostraca
-      // wrote or merged any files; if nothing changed on disk,
-      // voxgig-model's resolveModel cache short-circuits the re-read.
       const jfiles = jres?.files
       const reload = !!jfiles && (
         (jfiles.written?.length ?? 0) > 0 ||
@@ -486,7 +464,9 @@ ApiDef.makeBuild = async function(opts: ApiDefOptions) {
 
     const ctrl = build.spec.buildargs?.apidef?.ctrl || {}
 
-    return await apidef.generate({ model, build, config, ctrl })
+    // `buildctx` is the model build's own context, shared across its pre and
+    // post steps, and is where the resolved definition is published.
+    return await apidef.generate({ model, build, config, ctrl, buildctx: _ctx })
   }
 
   build.step = 'pre'
@@ -558,4 +538,13 @@ export {
   nom,
   VALID_CANON,
   CANON_ONE,
+
+  operationFacts,
+  operationIndex,
+  resolvedSpec,
+}
+
+export type {
+  OperationFacts,
+  ResolvedSpec,
 }

package/src/builder/entity/entity.ts

@@ -49,9 +49,6 @@ function resolveEntity(
 
     entityFiles.push({ name: entityFile, src: entitySrc })
 
-    // `./` — aontu 0.65 reads a bare single-segment include as a PACKAGE
-    // name (ADR-039), so `@"account.aon"` now resolves against the package
-    // stores and refuses. A sibling file has to say it is one.
     barrel.push(`@"./${Path.basename(entityFile)}"`)
   }))
 
@@ -69,23 +66,6 @@ function resolveEntity(
 }
 
 
-// Garbage-collect orphaned entity model files.
-//
-// The builder above EMITS one <outprefix><name>.aon per derived entity but
-// never removes anything, so an entity that disappears from the def — a spec
-// rename, a dropped path, a schema rename that changes the derived entity
-// name — leaves its old file behind on every regen. The orphan is not in the
-// regenerated entity-index barrel, so it is silently dead weight at best; at
-// worst a later hand-include resurrects a stale surface.
-//
-// Deletion is guarded three ways, so nothing a user could own is touched:
-//   1. only `<outprefix>*.aon` / `*.aontu` files in the entity folder
-//      (a different outprefix belongs to a different def sharing the folder);
-//   2. the current entity set and the index barrel are always kept;
-//   3. the file must START with the generated header (`# Entity: `) — a file
-//      apidef did not write is left alone.
-//
-// GC failure must never fail a build: errors are logged and swallowed.
 function gcEntityFiles(
   fs: any,
   log: any,
@@ -110,11 +90,6 @@ function gcEntityFiles(
   }
 
   for (const entry of entries) {
-    // BOTH extensions are candidates. `.aon` is what the builder emits
-    // now; `.aontu` is what it emitted before the rename, and such files
-    // are orphaned by definition — the regenerated index barrel no longer
-    // includes them. The `# Entity: ` header guard below still applies, so
-    // only a file apidef itself wrote is ever removed.
     if (!entry.endsWith('.aon') && !entry.endsWith('.aontu')) { continue }
     if (!entry.startsWith(prefix)) { continue }
     if (keep.has(entry)) { continue }
@@ -143,14 +118,6 @@ function gcEntityFiles(
 
 
 function fieldAliases(_entity: any): string {
-  // Field aliasing (mapping e.g. a `<name>_id` field onto the canonical
-  // `id`) is not currently implemented. The original heuristic referenced
-  // properties that don't exist on the entity at this stage
-  // (`entity.field`, `op.param`, `p.keys` — entities carry `fields`, ops
-  // carry `points`, and `each` stamps `key$`), so it always produced `{}`
-  // and would have thrown if any branch ran. Emit an empty alias map
-  // explicitly until the alias semantics are specified.
-  // Parity: go/builder.go buildFieldAliases (also `{}`).
   return '{}'
 }
 

package/src/builder/entity/info.ts

@@ -33,10 +33,6 @@ function resolveInfo(
 
   const modelInfo = { main: { kit: { info: kit.info } } }
 
-  // .trim() first so substring(1, len-1) strips the wrapping `{` and `}`.
-  // Without it, formatJSONIC's trailing newline is removed instead of the
-  // closing brace, leaving a dangling `}` in the output. Mirrors the sibling
-  // entity builder (builder/entity/entity.ts), which trims for this reason.
   let modelDefSrc = formatJSONIC(modelInfo).trim()
 
   modelDefSrc =

package/src/builder/flow.ts

@@ -1,5 +1,4 @@
 
-// TODO: move this to sdkgen
 
 
 import Path from 'node:path'
@@ -34,30 +33,20 @@ async function makeFlowBuilder(ctx: ApiDefContext): Promise<Function> {
     })
   }
 
-  /*
-  if ('heuristic01' === ctx.opts.strategy) {
-    try {
-      flows = await flowHeuristic01(ctx)
-    }
-    catch (err: any) {
-      err.foo = { x: 1, y: [2] }
-      err.foo.z = err.foo
+
+  const flownames: string[] = []
+  each(flows, (flow: any) => flownames.push(String(flow.name)))
+  const filebase = flowFileBases(flownames)
+
+  for (const name of flownames) {
+    if (name !== filebase[name] && ctx.warn) {
       ctx.warn({
         step: 'flow',
-        note: 'Unable to resolve flows due to unexpected error: ' + err.message,
-        err,
+        note: 'flow name ' + name + ' collides with another when case is' +
+          ' ignored: file written as ' + filebase[name] + '.aon'
       })
-      return flowBuilder
     }
   }
-  else {
-    ctx.warn({
-      step: 'flow',
-      note: 'Unable to resolve flows: unknown guide strategy: ' + ctx.opts.strategy
-    })
-    return flowBuilder
-  }
-  */
 
   flowBuilder = () => {
 
@@ -70,7 +59,7 @@ async function makeFlowBuilder(ctx: ApiDefContext): Promise<Function> {
         let flowfile =
           Path.join(ctx.opts.folder, 'flow',
             (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) +
-            flow.name + '.aon')
+            (filebase[flow.name] || flow.name) + '.aon')
 
         let flowModelSrc = formatJsonSrc(JSON.stringify(flow, null, 2))
 
@@ -79,8 +68,6 @@ async function makeFlowBuilder(ctx: ApiDefContext): Promise<Function> {
 main: ${KIT}: flow: ${flow.name}:
 ` + flowModelSrc
 
-        // `./` — see the entity barrel: aontu 0.65 reads a bare
-        // single-segment include as a package name and refuses it.
         barrel.push(`@"./${Path.basename(flowfile)}"`)
 
         File({ name: Path.basename(flowfile) }, () => Content(flowsrc))
@@ -100,5 +87,33 @@ main: ${KIT}: flow: ${flow.name}:
 
 
 export {
-  makeFlowBuilder
+  makeFlowBuilder,
+  flowFileBases,
+}
+
+
+// Flow file base names, unique when case is ignored. Every member of a
+// colliding group is suffixed in sorted-name order, so no member keeps the
+// bare name and the result is the same on every run. Names that do not
+// collide are returned unchanged.
+function flowFileBases(names: string[]): { [name: string]: string } {
+  const bylower: { [lower: string]: string[] } = {}
+  for (const name of names) {
+    const lower = name.toLowerCase()
+    bylower[lower] = bylower[lower] || []
+    bylower[lower].push(name)
+  }
+
+  const base: { [name: string]: string } = {}
+  for (const lower of Object.keys(bylower)) {
+    const group = bylower[lower].sort()
+    if (1 === group.length) {
+      base[group[0]] = group[0]
+    }
+    else {
+      group.forEach((name, i) => (base[name] = name + '__' + (i + 1)))
+    }
+  }
+
+  return base
 }

package/src/desc.ts

@@ -8,22 +8,10 @@ import type { ParameterDef } from './def'
 
 
 
-// // Intermediate Guide types used during analysis
-// type GuidePathRename = {
-//   param?: Record<string, string>
-// }
 
-// type GuideOp = {
-//   method: MethodName
-// }
 
-// type GuidePath = {
-//   rename?: GuidePathRename
-//   op?: Record<string, GuideOp>
-// }
 
 
-// Component analysis description
 type CmpDesc = {
   namedesc?: any,
   path_rate: number,
@@ -52,7 +40,6 @@ type MethodDesc = {
 }
 
 
-// Method entity relationship analysis
 type MethodEntityDesc = {
   ref: string
 
@@ -79,7 +66,6 @@ type MethodEntityDesc = {
 }
 
 
-// Entity analysis description
 type EntityDesc = {
   name: string
   origname: string
@@ -90,7 +76,6 @@ type EntityDesc = {
 }
 
 
-// Entity path relationship analysis
 type EntityPathDesc = {
   op: Record<string, any>
   pm: PathMatch
@@ -123,16 +108,13 @@ type PathSegment = {
 }
 
 
-// Path analysis description
 type PathDesc = {
   orig: string
   method: MethodName
   segments: PathSegment[]
-  // rename: GuidePathRename
   rename: {
     param?: Record<string, any>
   }
-  // op: GuidePath["op"]
   op: Record<string, {
     method: any
     transform: {
@@ -149,16 +131,12 @@ type PathDesc = {
 }
 
 
-// Operation analysis description
 type OpDesc = {
   paths: PathDesc[]
 }
 
 
 export type {
-  //  GuidePathRename,
-  //  GuideOp,
-  //  GuidePath,
   CmpDesc,
   BasicMethodDesc,
   MethodDesc,

package/src/guide/graphql01.ts

@@ -1,22 +1,5 @@
 /* Copyright (c) 2024-2026 Voxgig, MIT License */
 
-// GraphQL guide strategy: classify schema root fields into entities and
-// operations, the way heuristic01 classifies REST paths.
-//
-// Classification is SHAPE FIRST, NAME SECOND. Verb spellings diverge wildly
-// between GraphQL ecosystems (Hasura `insert_x_one`, Amplify `createTodo`,
-// Linear `issueCreate`, PostGraphile `createUser` — and PostGraphile's
-// inflector plugin can change them wholesale), but the type shapes do not:
-// a query returning the entity type behind a single required id argument is
-// a load in every one of them.
-//
-// Anything on Mutation that touches an entity but matches no CRUD shape
-// becomes an ACTION on a canonical op, reaching the SDK as an
-// `$action`-discriminated point — the same mechanism REST action paths
-// (/planet/{id}/terraform) already use. Nothing is ever dropped silently.
-//
-// `classifyGraphQLField` is a pure function of plain JSON, so it is driven
-// by a shared TSV fixture and can be ported to Go unchanged.
 
 import { each } from 'jostraca'
 
@@ -49,9 +32,7 @@ type GqlRetShape = {
   entity?: string
   // Connection only: the field holding the node array ('nodes' | 'edges').
   nodes?: string
-  // Payload only: the field the entity is wrapped in, if any.
   unwrap?: string
-  // Payload only: a delete-ish payload carries no entity.
   deleteish?: boolean
 }
 
@@ -63,7 +44,6 @@ type GqlArgSig = {
 }
 
 
-// Everything the classifier needs about one root field.
 type GqlFieldSig = {
   optype: 'query' | 'mutation'
   name: string
@@ -101,8 +81,6 @@ const MACHINERY_RE =
   /(Connection|Edge|PageInfo|Payload|Input|Filter|Comparator|Sort|OrderBy)$/
 
 
-// Strip a leading entity name off a mutation field name, returning the
-// residual verb. `issueCreate` -> `Create`; `createIssue` -> `create`.
 function splitEntityVerb(fieldName: string, entity: string): string {
   const lowerField = fieldName.toLowerCase()
   const lowerEnt = entity.toLowerCase()
@@ -117,14 +95,6 @@ function splitEntityVerb(fieldName: string, entity: string): string {
 }
 
 
-// Does this field take a required id-ish argument?
-//
-// Any required id counts, not just a lone one: a command like
-// `planetForbid(id: String!, forbid: Boolean!)` addresses an existing record
-// just as much as `planetArchive(id: String!)` does. Requiring it to be the
-// only required argument made an operation stop looking id-addressed the
-// moment the API made a second argument mandatory, which flipped it from an
-// update action to a create.
 function idArg(args: GqlArgSig[]): GqlArgSig | undefined {
   return args.find(
     (a: GqlArgSig) => a.reqd && /^(id|.*Id)$/i.test(a.name))
@@ -165,13 +135,11 @@ function classifyGraphQLField(
   const id = idArg(sig.args)
 
   if ('query' === sig.optype) {
-    // Connection or list of the entity -> list.
     if ('connection' === ret.kind || 'list' === ret.kind) {
       why.push('query:' + ret.kind)
       return { entity, op: 'list', optype: 'query', why }
     }
 
-    // Single entity behind one required id -> load.
     if ('entity' === ret.kind) {
       if (null != id) {
         why.push('query:entity:id=' + id.name)
@@ -193,7 +161,6 @@ function classifyGraphQLField(
     return { exclude: true, why }
   }
 
-  // --- mutation ---
   const verb = splitEntityVerb(sig.name, entity).replace(/^[_-]+/, '')
   const input = sig.inputTypeName ?? ''
 
@@ -204,14 +171,12 @@ function classifyGraphQLField(
     return { entity, op: 'create', optype: 'mutation', why }
   }
 
-  // update: <Entity>UpdateInput, or an update-ish verb.
   const updateByInput = new RegExp('^' + entity + '(Update|Edit|Patch|Set)Input$', 'i').test(input)
   if (updateByInput || UPDATE_RE.test(verb)) {
     why.push(updateByInput ? 'mutation:input:' + input : 'mutation:verb:' + verb)
     return { entity, op: 'update', optype: 'mutation', why }
   }
 
-  // remove: a delete-ish verb.
   if (REMOVE_RE.test(verb)) {
     why.push('mutation:verb:' + verb)
     return { entity, op: 'remove', optype: 'mutation', why }
@@ -249,7 +214,6 @@ function deriveRetShape(
     return { kind: 'other' }
   }
 
-  // Relay connection: has pageInfo plus nodes and/or edges.
   const fnames = Object.keys(named.fields)
   if (fnames.includes('pageInfo') &&
     (fnames.includes('nodes') || fnames.includes('edges'))) {
@@ -289,9 +253,6 @@ function deriveRetShape(
         !/^(errors?|userErrors?)$/i.test(fname)
     })
 
-    // Prefer the field whose name matches the payload's own entity prefix
-    // (IssuePayload -> issue), which is the convention every CRUD-regular
-    // GraphQL API follows; fall back to the single remaining candidate.
     const prefix = named.name.replace(/Payload$/, '')
     const byName = candidates.find((fname: string) =>
       fname.toLowerCase() === prefix.toLowerCase() ||
@@ -314,7 +275,6 @@ function deriveRetShape(
     return { kind: 'other' }
   }
 
-  // A list of the entity is a list op even without connection machinery.
   if (field.list) {
     return { kind: 'list', entity: named.name }
   }
@@ -323,13 +283,11 @@ function deriveRetShape(
 }
 
 
-// Build the classifier signature for a root field.
 function fieldSig(
   optype: 'query' | 'mutation',
   field: GqlField,
   types: Record<string, GqlType>
 ): GqlFieldSig {
-  // The input-object argument, if any, drives create/update detection.
   let inputTypeName: string | undefined = undefined
   for (const arg of field.args) {
     const at = types[arg.type]
@@ -352,8 +310,6 @@ function fieldSig(
 }
 
 
-// Verb suffixes a mutation field name may carry, longest first so
-// `issueUnarchive` strips `Unarchive` rather than `Archive`.
 const NAME_VERBS = [
   'Unarchive', 'Archive', 'Delete', 'Remove', 'Destroy',
   'Create', 'Update', 'Insert', 'Upsert',
@@ -390,45 +346,16 @@ function nameEntityType(
 }
 
 
-// Entity model name from a GraphQL type name: Issue -> issue,
-// WorkflowState -> workflow_state (canonize handles the casing rules that
-// the REST path classifier already uses).
 function rawEntityName(typeName: string): string {
   return depluralize(canonize(normalizeFieldName(typeName)))
 }
 
 
-// The leading-digit guard is applied here rather than inherited: the REST
-// side gets it from `ensureMinEntityName`, which this path deliberately does
-// not call (its min-length padding is the REST classifier's rule, and
-// entities here merge by name on purpose). GraphQL type names cannot begin
-// with a digit, but they can begin with `_`, which `normalizeFieldName`
-// strips — so `_3DSSessions` reaches an SDK as the entity `3_ds_session` and
-// every generated language rejects the identifier.
 function entityName(typeName: string): string {
   return prefixLeadingDigit(rawEntityName(typeName))
 }
 
 
-// Two GraphQL types that canonize to ONE entity name merge, deliberately:
-// `_3DSSession` and `_3DSSessions` are the singular and plural spellings of
-// one thing, and `Issue`/`Issues` likewise. That is what canonicalization is
-// for, and the caller's `guide.entity[entname] ?? {…}` is how it happens.
-//
-// The leading-digit guard opens one collision that is NOT that. A guarded
-// name (`_3DSSessions` -> `3_ds_session` -> `n3_ds_session`) can land on a
-// name another type already owns natively (`N3DSSession` -> `n3_ds_session`).
-// Those are unrelated types, and merging them would fold two entities' fields
-// and ops together under a name whose `orig` records only the first — with no
-// second guide entry for a user to correct, since guide.aon is the only
-// correction surface (ADR-002).
-//
-// So a collision between a guarded name and an unguarded one takes a numeric
-// suffix, the same convention `ensureMinEntityName` uses on the REST side.
-// The scope is exactly the collisions this guard creates: when both names are
-// guarded, or neither is, the merge is what it was before the guard existed
-// and stands untouched. The same type re-encountered on another root field
-// always reuses its own entry.
 function resolveEntityName(
   typeName: string,
   entities: Record<string, GuideEntity>,
@@ -460,7 +387,6 @@ function newGuidePath(): GuidePath {
 }
 
 
-// The GraphQL guide strategy.
 async function graphql01(ctx: ApiDefContext): Promise<Guide> {
   const def: GqlDef = ctx.def
   const profile: GqlProfile = (ctx.opts.profile ?? 'none') as GqlProfile
@@ -493,7 +419,6 @@ async function graphql01(ctx: ApiDefContext): Promise<Guide> {
   ]
 
   for (const root of roots) {
-    // Sorted iteration: byte-stable guide output.
     for (const fname of Object.keys(root.fields).sort()) {
       guide.metrics.count.field++