aontu 0.60.0 → 0.62.0

package/src/val/NomFuncVal.ts

@@ -0,0 +1,287 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+// `nom` -- NAME TRANSFORMATION, THE GENERAL CASE (SPIKE,
+// docs/design/JOSTRACA.0.md).
+//
+// Generated code is mostly names, and no two targets spell them the
+// same way: one model field is `user_id` in SQL, `userId` in
+// TypeScript, `UserID` in Go, `USER_ID` in an environment variable and
+// `user-id` in a URL. Before this, aontu had whole-string `upper` and
+// `lower` and nothing else, so the spike's own worked example wrote
+// `Planet` out by hand rather than deriving it -- `upper("planet")` is
+// `PLANET`.
+//
+//   nom(s)                  every spelling, as a map
+//   nom(s, style)           one spelling
+//   nom(s, acronyms)        every spelling, with an acronym set
+//   nom(s, style, acronyms) one spelling, with an acronym set
+//
+// THE SOURCE FORMAT IS NOT DECLARED, and that is what makes this the
+// general case rather than a family of pairwise converters. A name is
+// SPLIT INTO WORDS first -- `user_id`, `userId`, `UserID`, `USER_ID`,
+// `user-id`, `user.id` and `user/id` all split to `[user, id]` -- and
+// then rendered in the target style. N formats in and M out is one
+// splitter and M renderers, not N*M.
+//
+// THE SPLITTER IS THE RENDERER'S OWN (`splitWords`, ts/src/lower.ts):
+// the same one `aontu:profile`'s `%case` uses to lower a declaration,
+// so a name derived here and a name the renderer derives cannot
+// disagree. It breaks at `_`, `-` and space, at a lower-to-upper
+// boundary, at a letter-to-digit boundary either way, and before the
+// last capital of a capital run a lower case letter follows
+// (`HTTPServer` is HTTP, Server).
+//
+// `.` AND `/` ARE NORMALISED HERE, not in the splitter. A dotted path
+// and a slash path are name formats an author converts FROM, but the
+// splitter's behaviour is pinned in cross-port parity by the
+// renderer's rows, so the extra separators are this function's
+// vocabulary and are folded to `_` before it is asked. The same
+// boundary applies to the four styles below that `caseName` does not
+// serve: `title`, `text`, `dot` and `path` are nom's, and
+// `aontu:profile`'s `%case` set is unchanged.
+//
+// THE ACRONYM SET is the reason a style alone is not enough. `ledgerId`
+// is `LedgerID` in Go and `ledgerId` in TypeScript, which is a fact
+// about the TARGET and not about the name -- so it is an argument, and
+// a document generating for two targets passes a different one to each.
+//
+// SPIKE SCOPE. TypeScript only, so -- as with the component primitives
+// -- deliberately absent from test/spec/signature.tsv, BUILTIN_FUNCS
+// and grammar/, all pinned in cross-port parity. Arity and argument
+// shape are refused here rather than by the parse-time table or the
+// signature gate, and every refusal is `invalid-arg`, because a new
+// code needs a row in test/spec/errcodes.tsv and an entry in BOTH
+// ports' tables.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import {
+  splitWords,
+  caseName,
+  lowerASCII,
+  capitalise,
+} from '../lower'
+
+import { MapVal } from './MapVal'
+import { StringVal } from './StringVal'
+import { FuncBaseVal } from './FuncBaseVal'
+
+
+// The styles, and the map's keys. The first five are `caseName`'s --
+// `aontu:profile`'s `%case` vocabulary, shared with the renderer --
+// and the last four are nom's own (see the note above). `as-is` is
+// not among them: it is the profile's way of saying "do nothing",
+// which is not a spelling anyone asks a namer for.
+const NOM_STYLES = [
+  'camel',   // userId
+  'dot',     // user.id
+  'kebab',   // user-id
+  'pascal',  // UserId
+  'path',    // user/id
+  'snake',   // user_id
+  'text',    // User id
+  'title',   // User Id
+  'upper',   // USER_ID
+]
+
+// nom's style name -> the `%case` style `caseName` serves. `upper` and
+// `text` are nom's spellings: `screaming` is what `aontu:profile` calls
+// SCREAMING_SNAKE and that name is pinned cross-port, so the mapping
+// lives here rather than in the shared vocabulary.
+const CASENAME_STYLES: Record<string, string> = {
+  camel: 'camel',
+  kebab: 'kebab',
+  pascal: 'pascal',
+  snake: 'snake',
+  upper: 'screaming',
+}
+
+
+// One name in one style, or undefined when the style is not one, or
+// when the name holds no words at all.
+function styleName(name: string, style: string, acronyms: string[]):
+  string | undefined {
+  // `.` and `/` are nom's separators, folded before the shared
+  // splitter is asked (see the note above). Everything else that is
+  // not a separator is word content: a `$` or a `@` rides into the
+  // word it sits in, which is why `nom` renames a spelled path's
+  // text and does not tidy it.
+  const src = name.replace(/[./]/g, '_')
+
+  // A NAME WITH NO WORDS IS NOT A NAME, and it is refused in every
+  // style. `caseName` answers its INPUT for one (it is lowering a
+  // declaration, where the name has already been vetted), so
+  // `nom("_", pascal)` came back as `"_"` while `nom("_")`
+  // refused -- the same argument, accepted by one spelling of the
+  // call and refused by the other.
+  const words = splitWords(src)
+  if (0 === words.length) {
+    return undefined
+  }
+
+  const cased = CASENAME_STYLES[style]
+  if (undefined !== cased) {
+    return caseName(src, cased, acronyms)
+  }
+
+  if ('dot' === style) {
+    return words.map(lowerASCII).join('.')
+  }
+  if ('path' === style) {
+    return words.map(lowerASCII).join('/')
+  }
+  if ('title' === style) {
+    return words.map((w) => capitalise(w, acronyms)).join(' ')
+  }
+  if ('text' === style) {
+    // Sentence case: the first word capitalised, the rest lower --
+    // EXCEPT an acronym, which stays one, because `ledger id` loses
+    // what `ID` was. Membership in the set decides that, not how the
+    // input happened to spell the word: asking whether `capitalise`
+    // changed it made `nom("ledgerId", text, [ID])` answer
+    // `Ledger id` while `nom("ledgerID", text, [ID])` answered
+    // `Ledger ID` -- the same name, two answers, decided by its
+    // source spelling, which is the one thing a namer must not do.
+    const isAcronym = (w: string) =>
+      acronyms.some((a) => lowerASCII(a) === lowerASCII(w))
+    return [capitalise(words[0], acronyms)]
+      .concat(words.slice(1).map((w) =>
+        isAcronym(w) ? capitalise(w, acronyms) : lowerASCII(w)))
+      .join(' ')
+  }
+
+  return undefined
+}
+
+
+// The text a value carries, when it is a concrete string. A path is a
+// string too (ScalarKindVal's Path sits under String), so a spelled
+// address may be renamed like any other text.
+function textOf(v: Val | undefined): string | undefined {
+  const s: any = v
+  return (true === s?.isScalar && 'string' === typeof s.peg) ? s.peg : undefined
+}
+
+
+// An acronym set: a list of concrete strings, or undefined when the
+// value is not one.
+function acronymsOf(v: Val | undefined): string[] | undefined {
+  const l: any = v
+  if (true !== l?.isList) {
+    return undefined
+  }
+  const out: string[] = []
+  for (const el of l.peg as Val[]) {
+    const t = textOf(el)
+    if (undefined === t || '' === t) {
+      return undefined
+    }
+    out.push(t)
+  }
+  return out
+}
+
+
+class NomFuncVal extends FuncBaseVal {
+  isNamerFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new NomFuncVal(spec)
+  }
+
+  funcname() {
+    return 'nom'
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]): Val {
+    if (args.length < 1 || 3 < args.length) {
+      return makeNilErr(ctx, 'invalid-arg', this, undefined, 'arity')
+    }
+
+    const name = textOf(args[0])
+    if (undefined === name || '' === name) {
+      return makeNilErr(ctx, 'invalid-arg', this, args[0], 'name')
+    }
+
+    // THE SECOND ARGUMENT SAYS WHICH OF THE FOUR CALLS THIS IS, by
+    // its shape rather than by its position: a STRING is the style, a
+    // LIST is the acronym set. The same rule the component primitives
+    // read their spec by, and it is what keeps the acronym set
+    // reachable from the map form without a placeholder argument.
+    let style: string | undefined
+    let acronyms: string[] = []
+
+    if (2 <= args.length) {
+      const second: any = args[1]
+      if (true === second?.isList) {
+        if (3 === args.length) {
+          return makeNilErr(ctx, 'invalid-arg', this, args[2], 'arity')
+        }
+        const acr = acronymsOf(second)
+        if (undefined === acr) {
+          return makeNilErr(ctx, 'invalid-arg', this, second, 'acronyms')
+        }
+        acronyms = acr
+      }
+      else {
+        style = textOf(second)
+        if (undefined === style) {
+          return makeNilErr(ctx, 'invalid-arg', this, second, 'style')
+        }
+        if (3 === args.length) {
+          const acr = acronymsOf(args[2])
+          if (undefined === acr) {
+            return makeNilErr(ctx, 'invalid-arg', this, args[2], 'acronyms')
+          }
+          acronyms = acr
+        }
+      }
+    }
+
+    // One style: the string.
+    if (undefined !== style) {
+      const out = styleName(name, style, acronyms)
+      if (undefined === out) {
+        return makeNilErr(ctx, 'invalid-arg', this, args[1], 'style')
+      }
+      return this.place(new StringVal({ peg: out }, ctx))
+    }
+
+    // Every style: the map. Closed, because the nine keys ARE the
+    // vocabulary and a tenth is a typo -- `nom($.n).pascel` is
+    // refused where every other mistake in an aontu document is.
+    const peg: Record<string, Val> = {}
+    for (const s of NOM_STYLES) {
+      const out = styleName(name, s, acronyms)
+      if (undefined === out) {
+        return makeNilErr(ctx, 'invalid-arg', this, args[0], 'name')
+      }
+      peg[s] = new StringVal({ peg: out }, ctx)
+    }
+    const map = new MapVal({ peg }, ctx)
+    map.closed = true
+
+    return this.place(map)
+  }
+
+} /* node:coverage ignore next 6 */
+
+
+export {
+  NOM_STYLES,
+  NomFuncVal,
+}

package/src/val/PackFuncVal.ts

@@ -48,9 +48,9 @@ import { bagMembers } from './members'
 
 
 // The keys a data bag names, in the order the result must carry them,
-// or a code naming what is wrong with it. Shared with `each`, which
-// asks the same question of the same argument and answers it with the
-// values rather than the keys.
+// or a code naming what is wrong with it. `each` asks the same
+// question of the same argument and answers it with the values rather
+// than the keys (members.ts).
 function dataKeys(data: Val | undefined, ctx: AontuContext): string[] | string {
   // The candidates are the bag's MEMBERS -- what generation would
   // emit (./members.ts, BUGS.md §79) -- so a hidden key, or a hidden

package/src/val/RefVal.ts

@@ -657,7 +657,7 @@ class RefVal extends FeatureVal {
           // hidden IN ITS OWN RIGHT, and the verb's enumeration
           // (ts/src/val/members.ts, BUGS.md §79) needs to see that
           // mark to leave the member out, as generation does. A marked
-          // target lifts even there, or `each($.schema.entities, _)`
+          // target lifts even there, or `form($.schema.entities, _)`
           // under `schema: hide({...})` would see every entity as
           // hidden, since hide() marks to the leaves.
           const lifted = true !== (ctx as any).argsnap

package/src/val/TranslateFuncVal.ts

@@ -0,0 +1,182 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+// `translate` -- PER-CHARACTER SUBSTITUTION AND DELETION (SPIKE,
+// docs/design/JOSTRACA.0.md), after the `tr` command.
+//
+//   translate(s, from, to)   each character of `from` becomes the one
+//                            at the same position in `to`
+//   translate(s, from)       each character of `from` is deleted
+//
+// WHY IT IS NOT `rep`. `rep(s, pattern, sub)` matches a REGION and
+// substitutes text for it, so a per-character map is N calls over N
+// passes, each seeing the previous one's output -- and that composition
+// is wrong, not merely slow: `rep(rep(x, "a", "b"), "b", "a")` maps
+// every original `a` to `a` again. `translate` reads the source once
+// and consults a table, so `translate(x, "ab", "ba")` SWAPS them, which
+// is the operation `tr` exists for and the one a generator wants when
+// it rewrites a delimiter set or strips a character class.
+//
+// RANGES, as `tr` has them: `a-z` is every code point from `a` to `z`
+// inclusive, in both sets. A `-` first or last in a set is itself,
+// which is the only way to mean a literal one -- the sets take no
+// escape, because an aontu string literal has already processed its
+// own and a second escape layer over the first is a trap rather than a
+// feature. A descending range (`z-a`) is refused rather than read as
+// empty: it is always a mistake, and answering nothing for it hides it.
+//
+// A SHORT `to` PADS WITH ITS LAST CHARACTER, which is `tr`'s rule:
+// `translate(s, "abc", "x")` maps all three to `x`. An EMPTY or absent
+// `to` deletes instead, which is `tr -d`. Those are the same rule read
+// two ways -- there is no last character to pad with -- so the second
+// argument alone is deletion and needs no flag.
+//
+// A CHARACTER NAMED TWICE IN `from` TAKES ITS LAST MAPPING, because the
+// table is built left to right and a later entry overwrites an earlier.
+// `tr` does the same.
+//
+// CODE POINTS, NOT UTF-16 UNITS: one entry is one code point, so an
+// astral character maps as a unit and cannot be half-matched.
+//
+// NOT DONE, and deliberately: `tr`'s `-s` (squeeze repeats), `-c`
+// (complement) and its character classes (`[:alpha:]`). Each is a
+// second vocabulary on top of the sets, and none is needed by anything
+// the spike found. `re()` already spells a class for `rep`.
+//
+// SPIKE SCOPE. TypeScript only, so -- as with `nom` and the component
+// primitives -- deliberately absent from test/spec/signature.tsv,
+// BUILTIN_FUNCS and grammar/, all pinned in cross-port parity. Arity
+// and argument shape are refused here, and every refusal is
+// `invalid-arg`.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { StringVal } from './StringVal'
+import { FuncBaseVal } from './FuncBaseVal'
+
+
+// A set with its ranges expanded, or undefined when a range descends.
+// `-` first or last is a literal.
+function expandSet(set: string): string[] | undefined {
+  const cps = Array.from(set)
+  const out: string[] = []
+
+  for (let i = 0; i < cps.length; i++) {
+    const c = cps[i]
+    const next = cps[i + 1]
+    const after = cps[i + 2]
+
+    if ('-' === next && undefined !== after && 0 < i + 2) {
+      const lo = c.codePointAt(0) as number
+      const hi = after.codePointAt(0) as number
+      if (hi < lo) {
+        return undefined
+      }
+      for (let cp = lo; cp <= hi; cp++) {
+        out.push(String.fromCodePoint(cp))
+      }
+      i += 2
+      continue
+    }
+
+    out.push(c)
+  }
+
+  return out
+}
+
+
+// The text a value carries, when it is a concrete string.
+function textOf(v: Val | undefined): string | undefined {
+  const s: any = v
+  return (true === s?.isScalar && 'string' === typeof s.peg) ? s.peg : undefined
+}
+
+
+class TranslateFuncVal extends FuncBaseVal {
+  isTranslateFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new TranslateFuncVal(spec)
+  }
+
+  funcname() {
+    return 'translate'
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]): Val {
+    if (args.length < 2 || 3 < args.length) {
+      return makeNilErr(ctx, 'invalid-arg', this, undefined, 'arity')
+    }
+
+    const src = textOf(args[0])
+    if (undefined === src) {
+      return makeNilErr(ctx, 'invalid-arg', this, args[0], 'src')
+    }
+
+    const fromText = textOf(args[1])
+    if (undefined === fromText) {
+      return makeNilErr(ctx, 'invalid-arg', this, args[1], 'from')
+    }
+    const from = expandSet(fromText)
+    if (undefined === from) {
+      return makeNilErr(ctx, 'invalid-arg', this, args[1], 'from')
+    }
+
+    let to: string[] = []
+    if (3 === args.length) {
+      const toText = textOf(args[2])
+      if (undefined === toText) {
+        return makeNilErr(ctx, 'invalid-arg', this, args[2], 'to')
+      }
+      const expanded = expandSet(toText)
+      if (undefined === expanded) {
+        return makeNilErr(ctx, 'invalid-arg', this, args[2], 'to')
+      }
+      to = expanded
+    }
+
+    // The table, built left to right so a character named twice takes
+    // its last mapping. An empty `to` maps to nothing, which is the
+    // deletion: there is no last character to pad with.
+    const pad = 0 < to.length ? to[to.length - 1] : undefined
+    const table = new Map<string, string | undefined>()
+    for (let i = 0; i < from.length; i++) {
+      table.set(from[i], i < to.length ? to[i] : pad)
+    }
+
+    let out = ''
+    for (const c of Array.from(src)) {
+      if (table.has(c)) {
+        const sub = table.get(c)
+        if (undefined !== sub) {
+          out += sub
+        }
+        continue
+      }
+      out += c
+    }
+
+    return this.place(new StringVal({ peg: out }, ctx))
+  }
+
+} /* node:coverage ignore next 6 */
+
+
+export {
+  expandSet,
+  TranslateFuncVal,
+}

package/src/val/UpperFuncVal.ts

@@ -16,6 +16,7 @@ import { makeNilErr } from '../err'
 import { ScalarKindVal } from '../val/ScalarKindVal'
 import { makeScalarLike } from '../val/valutil'
 import { Decimal } from '../val/Decimal'
+import { caseRange, rangeArg } from './caserange'
 
 
 
@@ -49,7 +50,23 @@ class UpperFuncVal extends FuncBaseVal {
     // internal error.
     const arg = args?.[0]
     const oldpeg = arg?.peg
-    const peg = 'string' === typeof oldpeg ? oldpeg.toUpperCase() :
+
+    // THE RANGE (ts/src/val/caserange.ts): `start` names the first
+    // character of the run when it is zero or positive and the last
+    // when it is negative; `len` of -1, and the absent argument, are
+    // the source's length. Refused on a NUMBER, where a run of
+    // characters means nothing -- the numeric arm below is a ceiling,
+    // not a case mapping.
+    const start = rangeArg(args?.[1])
+    const len = rangeArg(args?.[2])
+    const ranged = undefined !== start || undefined !== len
+    if (ranged &&
+      (Number.isNaN(start as number) || Number.isNaN(len as number) ||
+        'string' !== typeof oldpeg)) {
+      return this.place(makeNilErr(ctx, 'invalid-arg', this, arg, 'range'))
+    }
+    const peg = 'string' === typeof oldpeg ?
+      caseRange(oldpeg, start ?? 0, len ?? -1, true) :
       'number' === typeof oldpeg ? Math.ceil(oldpeg) :
         // The exact leaves take an EXACT ceiling and keep their kind: a
         // biginteger is already integral so it is its own ceiling, and a

package/src/val/caserange.ts

@@ -0,0 +1,115 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+// THE RANGE `upper` AND `lower` TAKE.
+//
+//   upper(s)              the whole string
+//   upper(s, start)       from `start` to the end
+//   upper(s, start, len)  `len` characters
+//
+// `start` IS A BOUNDARY, NOT A CHARACTER. Zero or positive, it is
+// where the run BEGINS and the run reaches forward; negative, it counts
+// from the end and is where the run STOPS -- the character it lands on
+// is the first one NOT modified. One index, two directions, and no
+// second argument to say which:
+//
+//   upper("foo", 0, 1)      "Foo"      begins at 0, one character
+//   lower("FOOBAR", -3, -1) "fooBAR"   stops before the last three
+//
+// `len` of -1 means THE LENGTH OF THE SOURCE, which is how "and the
+// rest of it" is spelled in either direction, and is also the default:
+//
+//   lower("FOO", 1, -1)     "Foo"      from 1 to the end
+//   lower("FOOBAR", -1)     "foobaR"   everything but the last
+//
+// The exclusive reading is why `-0` is not a spelling: it is `0`, and
+// so begins a forward run. The whole string is `upper(s)`.
+//
+// BOTH ENDS CLAMP rather than refuse. A run reaching past either end
+// modifies as much of the string as exists, and one that lands wholly
+// outside it modifies nothing — an out-of-range index is not a
+// different KIND of answer, it is the same answer over a shorter run.
+//
+// CODE POINTS, NOT UTF-16 UNITS, so an index means the same thing in
+// both ports: one index is one Go rune. Twin: caseSpan/caseRange in
+// go/func.go.
+//
+// THE CASE MAPPING IS THE WHOLE-STRING ONE, applied to the slice, so
+// `upper(s)` and `upper(s, 0, -1)` are the same bytes. Two consequences
+// follow from full Unicode case mapping and are properties of the
+// mapping rather than of this range:
+//
+//   - THE RESULT MAY BE LONGER than the source, because full mapping is
+//     not one-in-one-out: `upper("straße", 3, 3)` is "straSSE".
+//   - FINAL SIGMA IS DECIDED WITHIN THE SLICE, since a slice taken out
+//     of its word has no following letter to see. A medial sigma cased
+//     alone lowercases as a final one.
+//
+// Both are stated here rather than worked around: silently widening
+// the slice to keep context would make the run something other than
+// what the author asked for.
+
+
+// The half-open code-point span [lo, hi) a (start, len) selects over a
+// string of `n` code points.
+export function caseSpan(n: number, start: number, len: number): [number, number] {
+  // -1 is the source's length, and so is any other negative: there is
+  // no meaningful run of "minus two" characters, and refusing one would
+  // be a second rule for no gain.
+  const span = len < 0 ? n : len
+
+  if (0 <= start) {
+    const lo = Math.min(start, n)
+    return [lo, Math.min(lo + span, n)]
+  }
+
+  // A negative start is where the run STOPS: the character it lands on
+  // is the first one not modified, so the run reaches back from it. No
+  // upper clamp: start is negative here, so n+start is below n by
+  // construction.
+  const hi = Math.max(0, n + start)
+  return [Math.max(0, hi - span), hi]
+}
+
+
+// `text` with the selected run cased. Outside the run the source is
+// returned verbatim, code point for code point.
+export function caseRange(
+  text: string, start: number, len: number, up: boolean
+): string {
+  const cps = Array.from(text)
+  const [lo, hi] = caseSpan(cps.length, start, len)
+  if (hi <= lo) {
+    return text
+  }
+  const mid = cps.slice(lo, hi).join('')
+  return cps.slice(0, lo).join('') +
+    (up ? mid.toUpperCase() : mid.toLowerCase()) +
+    cps.slice(hi).join('')
+}
+
+
+// The integer a range argument carries, or undefined when it is not
+// one. `undefined` for an absent argument is the caller's default, not
+// a refusal — these are optional.
+export function rangeArg(v: any): number | undefined {
+  if (null == v) {
+    return undefined
+  }
+  const p = (true === v?.isScalar) ? v.peg : undefined
+  if ('number' === typeof p && Number.isInteger(p)) {
+    return p
+  }
+  // A biginteger index is an index: a position in a string is small by
+  // construction, or it is not an index at all.
+  if ('bigint' === typeof p) {
+    const n = Number(p)
+    if (Number.isSafeInteger(n)) {
+      return n
+    }
+  }
+  // ONE REFUSAL for every way an argument can fail to be an index: not
+  // a scalar at all (a preference reaches here, the signature gate
+  // having nothing to check), a scalar of another kind, or a biginteger
+  // too large to be a position in a string.
+  return NaN
+}