@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/js/PrepareAuth_js.ts

@@ -64,6 +64,8 @@ module.exports = {
   const preamble = `
 const CRED_name = '${jsstr(spec.name)}'
 ${'cookie' === spec.where ? `
+const { cookieKeep } = require('./PrepareHeadersUtility')
+
 const COOKIE_header = 'cookie'
 ` : ''}
 const OPTION_apikey = 'apikey'${spec.basic && 'header' === spec.where ? `
@@ -71,6 +73,13 @@ const OPTION_secret = 'secret'` : ''}
 
 const NOTFOUND = '__NOTFOUND__'
 
+
+// The client's \`auth.name\` option, when set, replaces the name the API declares.
+function credName(name) {
+  return 'string' === typeof name && '' !== name ? ${caseFold(spec.where, 'name')} : CRED_name
+}
+
+
 function prepareAuth(ctx) {
   const utility = ctx.utility
 
@@ -92,10 +101,17 @@ ${cookieHelper(spec.where)}
 
   // Public APIs that need no auth omit the options.auth block entirely.
   if (null == options.auth) {
-    ${clear(spec.where)}
+    ${clear(spec.where, 'CRED_name')}
     return spec
   }
 
+  const name = credName(options.auth.name)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if (CRED_name !== name) {
+    ${clear(spec.where, 'CRED_name')}
+  }
+
   const apikey = getprop(options, OPTION_apikey, NOTFOUND)
 `
 
@@ -115,14 +131,14 @@ ${cookieHelper(spec.where)}
     const pass = NOTFOUND === secret || null == secret ? '' : secret
 
     if (noApikey) {
-      delprop(headers, CRED_name)
+      delprop(headers, name)
     }
     else {
       const b64 = Buffer.from(apikey + ':' + pass).toString('base64')
       // The joined, encoded pair is a wire form neither credential's own
       // registration covers.
       utility.cleanAdd(ctx, b64)
-      setprop(headers, CRED_name,
+      setprop(headers, name,
         options.auth.prefix ? options.auth.prefix + ' ' + b64 : b64)
     }
 
@@ -132,10 +148,10 @@ ${cookieHelper(spec.where)}
 
   return preamble + basicBlock + `
   if (NOTFOUND === apikey || null == apikey || '' === apikey) {
-    ${clear(spec.where)}
+    ${clear(spec.where, 'name')}
   }
   else {
-${place(spec.where)}
+${place(spec.where, 'name')}
   }
 
   return spec
@@ -155,18 +171,24 @@ function bag(where: string): string {
 }
 
 
+// Header names travel lower-cased; query and cookie names are case-sensitive.
+function caseFold(where: string, expr: string): string {
+  return 'header' === where ? expr + '.toLowerCase()' : expr
+}
+
+
 // A cookie has no header of its own: place() writes it into `cookie` as
-// `CRED_name=value`, so clear() must free that slot, not CRED_name.
-function clear(where: string): string {
+// `name=value`, so clear() frees that pair, not a header of that name.
+function clear(where: string, name: string): string {
   if ('query' === where) {
-    return 'delprop(query, CRED_name)'
+    return `delprop(query, ${name})`
   }
 
   if ('cookie' === where) {
-    return 'cookieSet(headers, null)'
+    return `cookieSet(headers, ${name}, null)`
   }
 
-  return 'delprop(headers, CRED_name)'
+  return `delprop(headers, ${name})`
 }
 
 
@@ -177,22 +199,12 @@ function cookieHelper(where: string): string {
   }
 
   return `
-  function cookieSet(headers, value) {
+  function cookieSet(headers, name, value) {
     const existing = getprop(headers, COOKIE_header, '')
-    const kept = []
-
-    if ('string' === typeof existing && '' !== existing) {
-      for (const part of existing.split(';')) {
-        const piece = part.trim()
-        if ('' === piece || piece === CRED_name || piece.startsWith(CRED_name + '=')) {
-          continue
-        }
-        kept.push(piece)
-      }
-    }
+    const kept = 'string' === typeof existing ? cookieKeep(existing, [name]) : []
 
     if (null != value) {
-      kept.push(CRED_name + '=' + value)
+      kept.push(name + '=' + value)
     }
 
     if (0 === kept.length) {
@@ -206,17 +218,17 @@ function cookieHelper(where: string): string {
 }
 
 
-function place(where: string): string {
+function place(where: string, name: string): string {
   if ('query' === where) {
-    return `    setprop(query, CRED_name, apikey)`
+    return `    setprop(query, ${name}, apikey)`
   }
 
   if ('cookie' === where) {
-    return `    cookieSet(headers, apikey)`
+    return `    cookieSet(headers, ${name}, apikey)`
   }
 
   return `    // Empty prefix (raw apiKey credential) must not add a leading space.
-    setprop(headers, CRED_name,
+    setprop(headers, ${name},
       options.auth.prefix ? options.auth.prefix + ' ' + apikey : apikey)`
 }
 

package/project/.sdk/src/cmp/js/ReadmeEntity_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,6 +20,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
   create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
 }
 
@@ -45,6 +46,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
@@ -100,7 +103,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape the runtime resolves path params from, so
       // the example always works.
@@ -122,7 +125,7 @@ const ${eVar} = await client.${entity.Name}().load(${loadArg})
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`ts
@@ -132,7 +135,7 @@ const ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)})
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member appears — including a
       // required id and parent keys like page_id — each with a type-correct

package/project/.sdk/src/cmp/js/ReadmeHowto_js.ts

@@ -102,9 +102,6 @@ const result = await client.direct({
   params: { id: 'example' },
 })
 
-if (result instanceof Error) {
-  throw result
-}
 if (result.ok) {
   console.log(result.status)  // 200
   console.log(result.data)    // response body

package/project/.sdk/src/cmp/js/ReadmeInstall_js.ts

@@ -17,9 +17,9 @@ npm install ${target.module.name}
 
   // Publish pending, as in the ts target: a tag may not exist, so a clone is
   // always offered. The js target needs no build.
-  const { releasesUrl, repoUrl, repo } = repoInfo(model)
-  Content(`This package is not yet published to npm. Install it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})), or from a
+  const { hostName, tagsUrl, repoUrl, repo } = repoInfo(model)
+  Content(`This package is not yet published to npm. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})), or from a
 clone:
 
 \`\`\`bash

package/project/.sdk/src/cmp/js/ReadmeIntro_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
@@ -20,7 +20,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   // Model-driven op list — only the operations the active entities actually
   // expose (a read-only entity has just list+load); never claim
   // create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

package/project/.sdk/src/cmp/js/ReadmeModel_js.ts

@@ -14,7 +14,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
   // Model-driven op rows for the shared entity interface: emit a
-  // load/list/create/update/remove row only for operations at least one active
+  // load/list/create/update/patch/remove row only for operations at least one active
   // entity actually exposes (a read-only entity has just list+load) — never
   // document an operation no entity has.
   const opUnion = new Set<string>()
@@ -25,15 +25,16 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria. |',
     create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity. |',
     update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity. |',
+    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity. |',
     remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   // Model-driven return-value bullets: describe only the operations that
   // actually exist (single-object ops among load/create/update, plus
   // list/remove) — never document return semantics for a missing op.
-  const singleOps = ['load', 'create', 'update'].filter((o) => opUnion.has(o))
+  const singleOps = ['load', 'create', 'update', 'patch'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const retBullets: string[] = []
   if (singleOps.length) {

package/project/.sdk/src/cmp/js/ReadmeQuick_js.ts

@@ -130,6 +130,23 @@ console.log(updated)
 `)
     }
 
+    if (opnames.includes('patch')) {
+      const patchLines = (idF
+        ? [`  ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.patch, idF, exampleEntity.name + '_id')},`]
+        : []).concat(exampleFields('patch'))
+      const patchBody = patchLines.length ? '\n' + patchLines.join('\n') + '\n' : ''
+      Content(`
+### Patch a ${eName}
+
+Sends only the fields given.
+
+\`\`\`js
+const patched = await client.${eName}().patch({${patchBody}})
+console.log(patched)
+\`\`\`
+`)
+    }
+
     if (opnames.includes('remove')) {
       Content(`
 ### Remove a ${eName}

package/project/.sdk/src/cmp/js/ReadmeRef_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -31,6 +31,12 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     returns: 'Promise<object>',
     desc: 'Update an existing entity. The data must include the entity `id`.',
   },
+  patch: {
+    sig: 'patch(data: object, ctrl?: object)',
+    returns: 'Promise<object>',
+    desc: 'Change part of an existing entity: only the fields given are sent. ' +
+      'The data must include the entity `id`.',
+  },
   remove: {
     sig: 'remove(match: object, ctrl?: object)',
     returns: 'Promise<void>',
@@ -159,8 +165,10 @@ Make a direct HTTP request to any API endpoint.
 | \`fetchargs.headers\` | \`object\` | Request headers (merged with defaults). |
 | \`fetchargs.body\` | \`any\` | Request body (objects are JSON-serialized). |
 | \`fetchargs.ctrl\` | \`object\` | Control options (e.g. \`{ explain: true }\`). |
+| \`fetchargs.ctrl.signal\` | \`AbortSignal\` | Aborts the request in flight: \`ok\` is then \`false\` and \`err.code\` is \`request_aborted\`. |
 
-**Returns:** \`Promise<{ ok, status, headers, data } | Error>\`
+**Returns:** \`Promise<{ ok, status, headers, data }>\`. On a failure
+\`ok\` is \`false\` and \`err\` holds the error.
 
 #### \`prepare(fetchargs?: object)\`
 
@@ -175,6 +183,15 @@ Alias for \`${model.Name}SDK.test()\`.
 
 **Returns:** \`${model.Name}SDK\` instance in test mode.
 
+#### Cancelling a call
+
+Every entity operation takes an optional \`ctrl\` object after its match or
+data, and an \`AbortSignal\` in \`ctrl.signal\` cancels the request in flight.
+The operation then rejects with an error whose \`code\` is
+\`request_aborted\` and whose \`cause\` is the signal's reason. A request
+whose signal has already aborted is not sent. \`stream()\` takes the signal
+as \`callopts.signal\`, and ends when it aborts.
+
 `)
 
 
@@ -228,7 +245,7 @@ const ${eVar} = client.${ent.Name}()
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks.
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -269,6 +286,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           // Show example
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
@@ -316,24 +337,32 @@ const result = await client.${ent.Name}().create({
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape the
             // runtime validates — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
             const updateLines = updateItems.map((it: any) =>
-              `  ${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+              `  ${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().update({
-${updateLines}  // Fields to update
+const result = await client.${ent.Name}().${opname}({
+${updateLines}  // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 })
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `Buffer`, `Uint8Array`, `ArrayBuffer`, `Blob`, stream or string',
+              once: 'a stream',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/js/ReadmeTopHowto_js.ts

@@ -12,10 +12,9 @@ const result = await client.direct({
   method: 'GET',
   params: { id: 'example' },
 })
-if (result instanceof Error) {
-  throw result
+if (result.ok) {
+  console.log(result.data)
 }
-console.log(result.data)
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/js/ReadmeTopTest_js.ts

@@ -42,7 +42,7 @@ const client = ${model.const.Name}SDK.test()
           `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
             it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)

package/project/.sdk/src/cmp/js/TestClean_js.ts

@@ -143,10 +143,34 @@ const SCENARIOS = [
   { name: 'coded', respond: (_url, _fetchdef, ctx) => {
     throw ctx.error('denied_' + CANARY.apikey, 'coded failure')
   } },
+  // fetch rejects a timed-out or aborted request with a DOMException, whose
+  // message is a getter with no setter.
+  { name: 'timeout', respond: (url) => {
+    throw new DOMException('timed out sending ' + CANARY.apikey + ' (URL was: "' + url + '")', 'TimeoutError')
+  } },
 ]
 
 
-function makeSdk(scenario, sinks, cleanopts, extra) {
+// Offline, as every generated suite is: the test OPTION resolves a required
+// server variable to test-<name>, and installs no transport.
+function offline(opts) {
+  return { ...opts, test: { active: true } }
+}
+
+
+// A client the sweep cannot build leaves nothing swept: a harness error, not a leak.
+function construct(opts) {
+  try {
+    return new SDK(offline(opts))
+  }
+  catch (err) {
+    throw new Error('clean harness: the client could not be constructed, so nothing was swept: ' +
+      (err?.message ?? String(err)))
+  }
+}
+
+
+function makeSdk(scenario, sinks, cleanopts, extra, auth) {
   const capture = (name) => (rec) => { sinks.push(...forms(name, rec)) }
   const feature = {}
   if (hasFeature('log')) {
@@ -175,7 +199,8 @@ function makeSdk(scenario, sinks, cleanopts, extra) {
   }
   // null builds the client with no clean block at all, as most callers do.
   if (null !== cleanopts) opts.clean = { values: CANARY.value, ...(cleanopts || {}) }
-  return new SDK(opts)
+  if (null != auth) opts.auth = auth
+  return construct(opts)
 }
 
 
@@ -183,7 +208,7 @@ function makeSdk(scenario, sinks, cleanopts, extra) {
 // arguments, else with every path parameter its points declare filled in.
 // Resolves to { accessor, op, match }.
 async function usableOp() {
-  const plain = new SDK({
+  const plain = construct({
     apikey: CANARY.apikey,
     utility: { fetcher: async () => response(200, { id: 'i1' }) },
   })
@@ -261,16 +286,19 @@ class StreamOkFeature extends BaseFeature {
 async function drive(sdk, target, ctrl, sinks) {
   // A caller may keep the record it passed rather than read ctrl.explain.
   const held = ctrl.explain
+  const entity = sdk[target.accessor]()
   let out = undefined
   let err = undefined
   try {
-    out = await sdk[target.accessor]()[target.op]({ ...target.match }, ctrl)
+    out = await entity[target.op]({ ...target.match }, ctrl)
   }
   catch (e) {
     err = e
   }
   if (undefined !== err) sinks.push(...forms('error', err))
   if (undefined !== out) sinks.push(...forms('result', out))
+  // Raw, as a caller copying the match into another query reads it.
+  sinks.push(...forms('match', entity.match()))
   if (null != ctrl.explain) sinks.push(...forms('explain', ctrl.explain))
   if (null != held && held !== ctrl.explain) sinks.push(...forms('explain:held', held))
   return err
@@ -305,12 +333,17 @@ describe('clean', () => {
       }
     }
 
+    // A name given at run time replaces the declared one: the match leaves
+    // out whichever name prepareAuth placed.
+    await drive(makeSdk(SCENARIOS[0], sinks, undefined, undefined, { name: 'zzcred' }),
+      target, {}, sinks)
+
     // A credential mistyped as an object is rejected by validation, whose
     // message quotes the value it rejected; with and without a clean block.
     for (const cleanblock of [{ clean: { values: CANARY.value } }, {}]) {
       let rejected = undefined
       try {
-        new SDK({ apikey: { value: CANARY.apikey }, ...cleanblock })
+        new SDK(offline({ apikey: { value: CANARY.apikey }, ...cleanblock }))
       }
       catch (e) {
         rejected = e
@@ -362,15 +395,22 @@ describe('clean', () => {
 
     // A feature's name is not a field name: only the sensitive names inside
     // its settings register. An entity block, of per-entity settings or seeded
-    // records keyed by entity name and id, is not read at all.
-    const featured = new SDK({ apikey: CANARY.apikey, feature: {
+    // records keyed by entity name and id, is not read at all, and nor are
+    // rbac's rules, keyed by entity and operation names.
+    const featured = construct({ apikey: CANARY.apikey, feature: {
       zzsecrets: { active: false, kind: 'PLAINSETTING-q8w2e4r6' },
       zzfeat: { active: false, apitoken: 'FEATTOKEN-z9y8x7w6' },
+      rbac: { active: false, rules: { 'zztoken.load': 'PLAINRULE-k7j5h3g1' } },
       test: { active: false, entity: { zztoken: { ZZTOKEN01: { note: 'PLAINRECORD-t5r3e1w9' } } } },
     }, entity: { zztoken: { alias: { zzkey: 'PLAINALIAS-m2n4b6v8' } } } })
     const fctx = { options: featured._options }
 
-    // The raw path returns its failure rather than throwing it.
+    // The raw path returns its failure rather than throwing it, a
+    // DOMException's included.
+    const timedout = await makeSdk(SCENARIOS[SCENARIOS.length - 1], sinks).direct({ path: 'raw' })
+    ok(false === timedout.ok && 'TimeoutError' === timedout.err?.name,
+      'a timed-out transport should fail direct() with its own error')
+    sinks.push(...forms('direct:timeout', timedout.err))
     const raw = await makeSdk(SCENARIOS[3], sinks).direct({ path: 'raw' })
     ok(false === raw.ok && null != raw.err, 'a transport failure should fail direct()')
     sinks.push(...forms('direct', raw.err))
@@ -384,6 +424,9 @@ describe('clean', () => {
     equal(leaked.length, 0, 'credential leaked through: ' +
       leaked.map((l) => l.name + ' [' + l.found.join(', ') + ']').join('; '))
 
+    // A DOMException is masked in place, and stays the error it was.
+    equal(errors['timeout/throw']?.name, 'TimeoutError', 'a timed-out operation should throw its own error')
+
     // The positive half: the slot the credential travelled in is masked,
     // and an unregistered token in a response header is masked by name.
     const notfound = errors['notfound/throw']
@@ -412,6 +455,7 @@ describe('clean', () => {
     equal(featured.utility().clean(fctx, 'token FEATTOKEN-z9y8x7w6'), 'token ' + MASK)
     equal(featured.utility().clean(fctx, 'record PLAINRECORD-t5r3e1w9'), 'record PLAINRECORD-t5r3e1w9')
     equal(featured.utility().clean(fctx, 'alias PLAINALIAS-m2n4b6v8'), 'alias PLAINALIAS-m2n4b6v8')
+    equal(featured.utility().clean(fctx, 'rule PLAINRULE-k7j5h3g1'), 'rule PLAINRULE-k7j5h3g1')
 
     const coded = errors['coded/throw']
     ok(null != coded, 'the coded scenario must throw')