@voxgig/apidef 6.3.2 → 6.3.6

package/src/transform/top.ts

@@ -105,10 +105,124 @@ const topTransform = async function(
     )
   }
 
+  // A short "what this API is" blurb and a canonical website link, for doc
+  // generators. Only set when derivable, so downstream can gate on them.
+  const summary = resolveSummary(def)
+  if (null != summary) {
+    kit.info.summary = summary
+  }
+  const website = resolveWebsite(def, kit.info.servers as any[])
+  if (null != website) {
+    kit.info.website = website
+  }
+
   return { ok: true, msg: 'top' }
 }
 
 
+// A short one-line description of the API's purpose: the spec's
+// `info.summary` (OpenAPI 3.1) when present, else the first prose sentence
+// of `info.description` with leading markdown headings/blank lines stripped
+// and the length capped. Returns undefined when no usable prose exists
+// (e.g. GitLab, whose top-level description is empty).
+function resolveSummary(def: any): string | undefined {
+  const info = def?.info ?? {}
+
+  const explicit = 'string' === typeof info.summary ? info.summary.trim() : ''
+  if ('' !== explicit) {
+    return firstSentence(explicit)
+  }
+
+  const desc = 'string' === typeof info.description ? info.description : ''
+  if ('' === desc.trim()) {
+    return undefined
+  }
+
+  const lines = desc.split('\n')
+  let i = 0
+  // Skip leading blank lines, ATX headings (`# ...`) and setext underlines.
+  while (i < lines.length &&
+    ('' === lines[i].trim() ||
+      /^\s*#{1,6}\s/.test(lines[i]) ||
+      /^\s*(-{2,}|={2,})\s*$/.test(lines[i]))) {
+    i++
+  }
+  // Take the first paragraph (up to the next blank line or heading).
+  const para: string[] = []
+  while (i < lines.length &&
+    '' !== lines[i].trim() &&
+    !/^\s*#{1,6}\s/.test(lines[i])) {
+    para.push(lines[i].trim())
+    i++
+  }
+  const paragraph = para.join(' ').trim()
+  return '' === paragraph ? undefined : firstSentence(paragraph)
+}
+
+
+// The first sentence of `text` (up to a `.`/`!`/`?` followed by whitespace
+// or end), whitespace-collapsed and length-capped with an ellipsis.
+function firstSentence(text: string): string {
+  const collapsed = text.replace(/\s+/g, ' ').trim()
+  const m = collapsed.match(/^(.+?[.!?])(\s|$)/)
+  let out = m ? m[1] : collapsed
+  const MAX = 240
+  if (out.length > MAX) {
+    out = out.slice(0, MAX - 1).trimEnd() + '…'
+  }
+  return out
+}
+
+
+// A canonical link back to the API's own website, in priority order:
+//   1. externalDocs.url          (the spec's explicit external link)
+//   2. info['x-logo'].href       (redoc homepage link)
+//   3. homepage from the server  (strip an api./developer./docs. subdomain)
+//   4. info.contact.url
+//   5. info.termsOfService
+function resolveWebsite(def: any, servers: any[]): string | undefined {
+  const info = def?.info ?? {}
+
+  const ext = def?.externalDocs?.url
+  if (isHttpUrl(ext)) return ext.trim()
+
+  const logoHref = info['x-logo']?.href
+  if (isHttpUrl(logoHref)) return logoHref.trim()
+
+  const home = homepageFromServer(servers?.[0]?.url)
+  if (null != home) return home
+
+  if (isHttpUrl(info.contact?.url)) return info.contact.url.trim()
+  if (isHttpUrl(info.termsOfService)) return info.termsOfService.trim()
+
+  return undefined
+}
+
+
+// Derive a homepage from an API server URL by dropping the path and an
+// `api.` / `developer.` / `docs.` / `www.` service subdomain — e.g.
+// `https://api.thesmsworks.co.uk/v1` -> `https://thesmsworks.co.uk`.
+function homepageFromServer(url: any): string | undefined {
+  if ('string' !== typeof url || '' === url.trim()) return undefined
+  try {
+    const u = new URL(url.includes('://') ? url : 'https://' + url)
+    let host = u.hostname
+    if ('' === host || !host.includes('.')) return undefined
+    host = host.replace(
+      /^(api|api-[a-z0-9]+|apis|developer|developers|docs?|www)\./i, '')
+    return u.protocol + '//' + host
+  }
+  catch (_e) {
+    return undefined
+  }
+}
+
+
+function isHttpUrl(v: any): boolean {
+  return 'string' === typeof v && /^https?:\/\//i.test(v.trim())
+}
+
+
 // Describe the spec's PRIMARY security scheme as model facts
 // (info.security): scheme key, type, where the credential goes (in/name),
 // and the value prefix for Authorization-header credentials. The primary
@@ -119,8 +233,13 @@ const topTransform = async function(
 // Prefix rules:
 //   http basic/bearer      -> 'Basic' / 'Bearer'
 //   oauth2 / openIdConnect -> 'Bearer' (access token in Authorization)
-//   apiKey in an Authorization header -> the scheme the API's own prose
-//     documents (e.g. `Authorization: OAuth <key>`), else 'Bearer'
+//   apiKey in an Authorization header -> the prefix the API's own prose
+//     documents (e.g. `Authorization: OAuth <key>`), else '' (raw). An
+//     `apiKey` scheme means "send the credential as-is" — a `Bearer`/etc.
+//     prefix is only implied by an `http`+`bearer` scheme or explicit
+//     prose, so absent evidence the key goes in raw (e.g. The SMS Works'
+//     `Authorization: <jwt>`). A user override is available via
+//     config.auth.prefix.
 //   apiKey in any other header/query/cookie -> '' (raw credential)
 function resolveSecurity(def: any): Record<string, string> | null {
   const schemes: Record<string, any> =
@@ -167,10 +286,12 @@ function resolveSecurity(def: any): Record<string, string> | null {
   else if ('apikey' === type) {
     if ('header' === String(out.in).toLowerCase() &&
       'authorization' === String(out.name).toLowerCase()) {
+      // Only adopt a prefix the API's prose actually documents; otherwise
+      // the apiKey goes in raw (no assumed 'Bearer').
       out.prefix =
         findAuthPrefix(scheme.description) ??
         findAuthPrefix(def.info?.description) ??
-        'Bearer'
+        ''
     }
     // else: raw credential in a named header/query/cookie — no prefix.
   }
@@ -179,23 +300,55 @@ function resolveSecurity(def: any): Record<string, string> | null {
 }
 
 
-// Extract the credential prefix from prose showing the Authorization
-// header format, e.g. `Authorization: OAuth 89a2...` or
-// `-H "Authorization: token <key>"`. The prefix must be a short word on
-// the SAME line, followed by something credential-shaped — a long token,
-// or a `<key>` / `{token}` / `$KEY` / `YOUR_...`-style placeholder. Bare
-// credentials (`Authorization: 89a2...`) and prose coincidences yield no
-// match.
+// Extract the credential prefix from a securityScheme's / info prose.
+// Three signals, in confidence order:
+//   1. An explicit `Authorization: <prefix> <cred>` line (any prefix word)
+//      — e.g. Statuspage's `Authorization: OAuth 89a2...`. The prefix must
+//      be a short word followed by something credential-shaped (a long
+//      token, or a `<key>` / `{token}` / `$KEY` / `YOUR_...` placeholder),
+//      so a bare `Authorization: 89a2...` doesn't match.
+//   2. A KNOWN scheme word (Bearer/OAuth/Token/Basic) shown as an example
+//      prefix — `Example: Bearer eyJ...` (NoFrixion's shape).
+//   3. A KNOWN scheme word named as the scheme — `the Bearer scheme`,
+//      `Bearer authentication`.
+// Returns null when nothing indicates a prefix (an apiKey then goes in raw).
 function findAuthPrefix(text: unknown): string | null {
   if ('string' !== typeof text || '' === text) {
     return null
   }
-  const m = text.match(
+
+  const explicit = text.match(
     /Authorization:[ \t]*([A-Za-z][A-Za-z0-9._-]{0,14})[ \t]+(?:<[^>\n]+>|\{[^}\n]+\}|\$[A-Za-z_][A-Za-z0-9_]*|[Yy][Oo][Uu][Rr][A-Za-z0-9_-]*|[A-Za-z0-9._~+/=-]{8,})/)
-  if (null == m) {
-    return null
+  if (null != explicit) {
+    return explicit[1]
   }
-  return m[1]
+
+  // A known scheme word as an example prefix, then a credential-shaped tail.
+  const example = text.match(
+    /(?:example|e\.g\.)[:\s][^\n]{0,20}?\b(Bearer|OAuth2?|Token|Basic)\b[ \t]+(?:<[^>\n]+>|\{[^}\n]+\}|[A-Za-z0-9._~+/=-]{6,})/i)
+  if (null != example) {
+    return canonAuthScheme(example[1])
+  }
+
+  // A known scheme word named as the auth scheme.
+  const named = text.match(
+    /\b(Bearer|OAuth2?|Token|Basic)\b[ \t]+(?:scheme|authentication|auth\b|credentials?)/i)
+  if (null != named) {
+    return canonAuthScheme(named[1])
+  }
+
+  return null
+}
+
+
+// Canonical casing for a known scheme word (Bearer/OAuth/Token/Basic).
+function canonAuthScheme(word: string): string {
+  const w = word.toLowerCase()
+  if (w.startsWith('oauth')) return 'OAuth'
+  if ('bearer' === w) return 'Bearer'
+  if ('token' === w) return 'Token'
+  if ('basic' === w) return 'Basic'
+  return word
 }
 
 
@@ -264,6 +417,9 @@ function stringifyInfoScalars(node: any): any {
 export {
   topTransform,
   resolveSecurity,
+  resolveSummary,
+  resolveWebsite,
+  homepageFromServer,
   findAuthPrefix,
 }
 

package/src/utility.ts

@@ -951,6 +951,34 @@ function canonize(s: string) {
 }
 
 
+// Namespace-qualified schema names (ASP.NET / Java style:
+// "NoFrixion.MoneyMoov.Models.PaymentRequests.MerchantPayment",
+// "com.example.api.Payment") describe the type by their LAST dotted
+// segment; the namespace prefix is packaging noise. Reduce to the last
+// meaningful segment — skipping version-ish ("v2", "10") or too-short
+// tails — so entity names derive from the type, not the namespace.
+function stripSchemaNamespace(name: string): string {
+  if (null == name || !name.includes('.')) return name
+  const segs = name.split('.')
+  for (let i = segs.length - 1; i >= 0; i--) {
+    const seg = segs[i]
+    if (seg.length >= 3 && !/^v?\d+$/i.test(seg)) {
+      return seg
+    }
+  }
+  return name
+}
+
+
+// Canonical form of an OpenAPI component schema name, for use as an
+// entity-name candidate and as the frequency-metric key. Must be applied
+// uniformly wherever schema refs are counted or resolved (MeasureRef,
+// ResolveEntityComponent, findcmps) so the metric keys stay consistent.
+function canonizeCmpName(orig: string): string {
+  return canonize(stripSchemaNamespace(orig))
+}
+
+
 // Sanitize a raw slug into a clean kebab-case string suitable for
 // conversion to a valid JS identifier (via camelify/snakify/etc).
 function sanitizeSlug(s: string): string {
@@ -1062,8 +1090,21 @@ function ensureMinEntityName(
   }
 
   if (padded !== name && null != existing[padded]) {
+    // The name was modified (truncated/sanitized) and collides with an
+    // existing entity. Only a collision between DIFFERENT origins needs a
+    // numeric suffix — the same original name re-encountered (e.g. the same
+    // long schema referenced by several methods on one path) must reuse the
+    // existing entity so its ops merge instead of minting phantom
+    // "<entity>2/3/4" entities. Entities record their pre-truncation name
+    // as `longname`; entries without one keep the old always-suffix rule.
+    if (existing[padded].longname === name) {
+      return padded
+    }
     let i = 2
     while (null != existing[padded + i]) {
+      if (existing[padded + i].longname === name) {
+        return padded + i
+      }
       i++
     }
     padded = padded + i
@@ -1073,18 +1114,53 @@ function ensureMinEntityName(
 }
 
 
+// Unconditional suffixes: framework noise, always stripped.
 const CMP_SUFFIXES = ['_rest_controller', '_controller', '_response', '_request']
+
+// Guarded suffixes: pagination wrappers ('_page_response', '_page') and
+// op-reply wrappers ('_create_response', '_update_response') fold wrapper
+// schemas (BeneficiaryPageResponse, MerchantTokenPage,
+// BeneficiariesCreateResponse, ...) into their base entity — but ONLY when
+// the remainder is itself a known component schema (the wrapper
+// convention). Without that guard a real noun gets mangled: an API whose
+// resource IS a page (LandingPage entity at /landing-pages) must keep
+// 'landing_page', not become 'landing'. Order matters: longer first, since
+// '_page_response'/'_create_response' also end with '_response'. Bare
+// '_create'/'_update' are never stripped: too likely part of a real noun.
+const CMP_GUARDED_SUFFIXES = ['_create_response', '_update_response', '_page_response', '_page']
+
 const CMP_PREFIXES = ['get_', 'post_', 'put_', 'delete_', 'patch_']
 
-function cleanComponentName(name: string): string {
+function cleanComponentName(
+  name: string,
+  isKnownCmp?: (canonizedRemainder: string) => boolean
+): string {
   let cleaned = name
+  let stripped = false
+
+  if (null != isKnownCmp) {
+    for (const suffix of CMP_GUARDED_SUFFIXES) {
+      if (cleaned.endsWith(suffix)) {
+        const parts = cleaned.split('_')
+        const suffixParts = suffix.split('_').filter(s => s !== '').length
+        const remainder = canonize(parts.slice(0, parts.length - suffixParts).join('_'))
+        if (remainder.length >= 3 && isKnownCmp(remainder)) {
+          cleaned = remainder
+          stripped = true
+        }
+        break
+      }
+    }
+  }
 
-  for (const suffix of CMP_SUFFIXES) {
-    if (cleaned.endsWith(suffix)) {
-      const parts = cleaned.split('_')
-      const suffixParts = suffix.split('_').filter(s => s !== '').length
-      cleaned = canonize(parts.slice(0, parts.length - suffixParts).join('_'))
-      break
+  if (!stripped) {
+    for (const suffix of CMP_SUFFIXES) {
+      if (cleaned.endsWith(suffix)) {
+        const parts = cleaned.split('_')
+        const suffixParts = suffix.split('_').filter(s => s !== '').length
+        cleaned = canonize(parts.slice(0, parts.length - suffixParts).join('_'))
+        break
+      }
     }
   }
 
@@ -1315,6 +1391,8 @@ export {
   formatJSONIC,
   validator,
   canonize,
+  canonizeCmpName,
+  stripSchemaNamespace,
   sanitizeSlug,
   slugToPascalCase,
   transliterate,