@voxgig/apidef 8.3.0 → 8.5.0

package/model/guide.aon

@@ -3,6 +3,48 @@ guide: entity: &: {
   active?: boolean
   name: key()
 
+  # COMPOSITE IDENTITY OVERRIDE.
+  #
+  # Some APIs address one record by several path parameters at once, with no
+  # single parameter that is the id: github needs {owner} and {repo} together
+  # to name a repository, and cloudsmith needs {owner}/{repo}/{identifier}
+  # for an entitlement. The model carries those as `id.parts`, joined by
+  # `id.sep` into the one id an SDK entity holds.
+  #
+  # apidef infers this from ADJACENT variable path segments, which is right
+  # far more often than not but cannot always be right: a trailing variable
+  # is sometimes a MODIFIER rather than part of the key. github's
+  # `/…/artifacts/{artifact_id}/{archive_format}` is the clear case —
+  # `archive_format` selects zip or tar, it does not identify the artifact —
+  # and no reading of the path alone distinguishes that from a genuine
+  # compound key.
+  #
+  # So state it here when the inference is wrong:
+  #
+  #   id: parts: [ 'owner', 'repo' ]   # this IS the compound key
+  #   id: composite: false             # it is not; the last param is the id
+  #
+  # An explicit `parts` wins over the inference. `composite: false` turns the
+  # inference off, which is what `archive_format` above wants.
+  #
+  # THE FLAG IS A BOOLEAN, NOT AN EMPTY `parts`. Writing `parts: []` reads as
+  # "no parts" but cannot work: aontu resolves an empty list to nothing, so
+  # the key arrives absent and is indistinguishable from never having been
+  # set — the inference then runs anyway. That was tried first.
+  #
+  # `sep` defaults to '/' and rarely wants changing: a slash cannot occur
+  # inside one path segment, so the join is unambiguous.
+  id?: {
+    parts?: [ &: string ]
+    sep?: string
+    composite?: boolean
+
+    # Corrects WHERE A PART LIVES in a response, per part, so a spec can fix
+    # one mapping without restating the others.
+    from?: &: string
+
+  }
+
   path: &: {
     active?: boolean
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/apidef",
-  "version": "8.3.0",
+  "version": "8.5.0",
   "main": "dist/apidef.js",
   "type": "commonjs",
   "types": "dist/apidef.d.ts",

package/src/guide/guide.ts

@@ -96,6 +96,26 @@ function migrateLegacyGuide(fs: any, folder: string, guideprefix: string): boole
 }
 
 
+// The first unresolved merge-conflict marker in a source, or null.
+//
+// Anchored at line start and requiring exactly the conventional seven
+// characters: a guide legitimately contains `>>>>>>> GENERATED` inside the
+// jostraca provenance comments it writes about itself, and `====` shows up in
+// prose. Only a real marker at column zero counts.
+function findConflict(src: string): { line: number, text: string } | null {
+  const lines = String(src || '').split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^(<{7}|>{7})(?!<|>)/.test(line) || /^={7}(?!=)\s*$/.test(line)) {
+      return { line: i + 1, text: line.slice(0, 80) }
+    }
+  }
+
+  return null
+}
+
+
 async function buildGuide(ctx: ApiDefContext): Promise<any> {
   const log = ctx.log
   const errs: any[] = []
@@ -135,6 +155,60 @@ async function buildGuide(ctx: ApiDefContext): Promise<any> {
 
   handleErrors(ctx, errs)
 
+  // A MERGE CONFLICT IN A GUIDE IS SAID OUT LOUD, HERE.
+  //
+  // The guide is 3-way merged: apidef regenerates the base guide from the
+  // spec and merges it over what the project already had. Change the spec
+  // enough — swap a 5-path definition for the API's whole 722-path one — and
+  // an edit the project made can no longer be reconciled, so the merge
+  // writes ordinary `<<<<<<<` / `=======` / `>>>>>>>` markers into the file.
+  //
+  // Nothing then read the file until aontu did, and aontu reports what it
+  // sees: `unexpected character(s): <<<<<<<`, thousands of lines into a
+  // generated file, with no hint that this is a merge conflict or which edit
+  // caused it. That cost a long detour — the failure was read as apidef
+  // hanging, and the real cause (one conflicted rename) sat two lines away
+  // from a marker nobody had looked for.
+  //
+  // The guide is a file apidef itself writes, so apidef is the right place to
+  // recognise its own merge output before handing it on.
+  // BOTH FILES, and the base guide is the one that usually has it: `guide.aon`
+  // is two @-includes a user rarely edits, while `base-guide.aon` is what
+  // apidef regenerates and merges. Checking only the top-level file found
+  // nothing and left aontu to report the marker.
+  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
+    }
+  }
+
+  handleErrors(ctx, errs)
+
 
 
 

package/src/model.ts

@@ -232,6 +232,29 @@ type ModelEntity = {
   id?: {
     name: string
     field: string
+    // COMPOSITE IDENTITY. Present only when the API addresses one record by
+    // MORE THAN ONE path parameter, so no single parameter is the id.
+    // github's repo is the case: GET /repos/{owner}/{repo} needs both, and
+    // neither alone names a repository.
+    //
+    // `parts` are those parameters in path order; `sep` joins them into the
+    // one `id` an SDK entity carries. Absent means the ordinary single-key
+    // entity, so downstream can branch on presence alone.
+    parts?: string[]
+    sep?: string
+    // WHERE EACH PART'S VALUE LIVES IN A RESPONSE, as a dotted path.
+    //
+    // The parts are PATH PARAMETER names and a response names its fields
+    // whatever it likes: github addresses a repo by `{owner}/{repo}` and
+    // returns the owner as an OBJECT, so the value is at `owner.login`, and
+    // the repository under `name`. Without this a consumer can address a
+    // record it was given the id of, but cannot put an id on a record the
+    // API returned.
+    //
+    // A part no rule resolves is left OUT, so an incomplete map says the id
+    // cannot be rebuilt for that entity — better than a confidently wrong id
+    // on a real record. guide.aon can state it instead.
+    from?: Record<string, string>
   }
   relations: ModelEntityRelations
 }