aontu 0.61.0 → 0.63.0

package/src/val/MoveFuncVal.ts

@@ -18,12 +18,10 @@ import {
 } from '../utility'
 
 
-
 import { FuncBaseVal } from './FuncBaseVal'
 import { PrefFuncVal } from './PrefFuncVal'
 
 
-
 class MoveFuncVal extends FuncBaseVal {
   isMoveFunc = true
 
@@ -55,23 +53,6 @@ class MoveFuncVal extends FuncBaseVal {
     if (!orig.isNil) {
       const src = orig.clone(ctx)
 
-      // THE HIDE-WALK ONLY RUNS WHEN THE CLONE IS A SEPARATE OBJECT.
-      //
-      // move() is the only function that marks the ORIGINAL rather than
-      // the clone -- that is how the value disappears from its old home
-      // and reappears at the destination. It relies on clone() returning
-      // something distinct to carry to the destination.
-      //
-      // TopVal.clone is the IDENTITY function, so for `move(top)` the
-      // clone and the original are the same object and the walk hid the
-      // very value being returned: the key vanished from generated output
-      // with no error, while canon still showed `x:top` -- the port
-      // disagreeing with itself.
-      //
-      // With the walk skipped, `move(top)` keeps `top` at the destination
-      // and then errors there because top is not generable, which is
-      // already what `x:top`, `x:copy(top)` and `x:pref(top)` do in both
-      // ports, and what `move(number)` does for the same reason.
       if (src !== orig) {
         if (src.isRef) {
           src.mark._hide_found = true
@@ -86,7 +67,6 @@ class MoveFuncVal extends FuncBaseVal {
       out = new PrefFuncVal({ peg: [src] }, ctx)
     }
 
-    // console.log('MOVE-resolve', orig, out)
 
     return out
   }

package/src/val/NilVal.ts

@@ -33,7 +33,6 @@ class NilVal extends Val {
   attempt?: string
   details?: Record<string, any>
 
-  // TODO: include Val generating nil, thus capture type
 
   // A Nil is an error - should not happen - unify failed
   // refactor ,make(spec,ctx)
@@ -79,28 +78,8 @@ class NilVal extends Val {
       }
     }
 
-    // THE PATH IS WHERE THE MEET IS, NOT WHERE THE OPERAND WAS WRITTEN
-    // (use-cases/BUGS.md §41). The operand path above decides the SITE
-    // correctly and the path only by accident: a value that arrives by
-    // REFERENCE is re-pathed to the referring field, and its children
-    // are re-pathed to that same field rather than rebased under it, so
-    // every conflict inside `q: $.M` reported `$.q` — the enclosing
-    // record, not the key to edit, and the SAME path for every one of
-    // its fields. The context has descended to the child by the time
-    // the meet fails, and Go reads the path off the tree position for
-    // exactly this reason.
-    //
-    // Only EXTENDS, never redirects: the context path is taken when the
-    // operand's path is a PREFIX of it, so a nil minted away from the
-    // descent (a func resolving an argument, a generator's own probe,
-    // an anchored `--at` run whose operand is already correctly placed)
-    // keeps the path its operand carries. Taking the context path
-    // unconditionally was tried and reverted -- it moved the closed-key,
-    // spread-template and every `--at` finding to the driving location,
-    // which is not where those belong.
-    if (null != ctx?.path && null != nil.path &&
-      nil.path.length < ctx.path.length &&
-      nil.path.every((p, i) => p === ctx.path[i])) {
+    if (null != ctx?.path && 0 < ctx.path.length &&
+      (null != bv || null == nil.path || 0 === nil.path.length)) {
       nil.path = [...ctx.path]
     }
 
@@ -145,9 +124,6 @@ class NilVal extends Val {
     let out = (super.clone(ctx, spec) as NilVal)
     out.why = this.why
 
-    // Should these clone?
-    // out.primary = this.primary?.clone()
-    // out.secondary = this.secondary?.clone()
     out.primary = this.primary
     out.secondary = this.secondary
 
@@ -156,7 +132,6 @@ class NilVal extends Val {
   }
 
 
-  // TODO: custom canon? useful for unknown function errors
   get canon() {
     return 'nil'
   }
@@ -200,15 +175,6 @@ class NilVal extends Val {
 }
 
 
-// Shared sentinel for transient "this unification branch failed"
-// markers. Used by DisjunctVal.unify to flag failed member trials
-// (and to dedup results) without allocating a fresh NilVal per
-// failure. The sentinel is filtered out before the disjunct result
-// is constructed, so its .why / .site / .primary fields are never
-// inspected by user-visible code.
-//
-// Do NOT use this sentinel for errors that may surface: those need
-// real NilVals with proper site/path info for descErr formatting.
 const TRIAL_NIL = new NilVal({ why: '|:trial-nil' }) /* node:coverage ignore next 7 */
 
 

package/src/val/NomFuncVal.ts

@@ -0,0 +1,200 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+
+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'
+
+
+const NOM_STYLES = [
+  'camel',   // userId
+  'dot',
+  'kebab',
+  'pascal',  // UserId
+  'path',
+  'snake',
+  'text',
+  'title',
+  'upper',   // USER_ID
+]
+
+// nom's style name -> the `%case` style `caseName` serves. `upper` and
+// `text` are nom's spellings: `screaming` is what `aontu:render` 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 {
+  const src = name.replace(/[./]/g, '_')
+
+  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) {
+    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 {
+    // Arity is checked at parse (funcArity); see the translate twin.
+    const name = textOf(args[0])
+    if (undefined === name || '' === name) {
+      return makeNilErr(ctx, 'invalid-arg', this, args[0], 'name')
+    }
+
+    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))
+    }
+
+    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/NumberVal.ts

@@ -20,11 +20,6 @@ import {
 } from '../utility'
 
 
-
-// The IEEE-754 binary64 leaf of the number tower. Its KIND is Float (the
-// keyword `float`), not the `number` supertype: `number` names the family
-// of numeric leaves and never tags a concrete value. The class name is
-// historical -- `number` used to name this leaf.
 class NumberVal extends ScalarVal {
   isNumber = true
 
@@ -35,7 +30,6 @@ class NumberVal extends ScalarVal {
     // Number.isFinite (not the coercing global isNaN, which lets null/''
     // through as "numbers") — only an actual finite number is valid.
     if (!Number.isFinite(spec.peg)) {
-      // TODO: use Nil?
       throw new AontuError('not-number: ' + spec.peg)
     }
 
@@ -57,8 +51,6 @@ class NumberVal extends ScalarVal {
         peer.kind === this.kind &&
         peer.peg === this.peg
       ) {
-        // Same kind (both Float) and equal value: integer/float no
-        // longer cross-unify, so peer is necessarily a NumberVal here.
         out = this
       }
       else if (peer.isTop) {
@@ -79,14 +71,6 @@ class NumberVal extends ScalarVal {
   }
 
 
-  // Canon must round-trip kind: reparsing the canon of a float-kind
-  // value has to yield a float-kind value again. A rendering with no
-  // '.' and no exponent (1 -> "1") would reparse as an integer, so it
-  // gains a ".0" suffix. Renderings that already carry a fraction, an
-  // exponent, or are NaN/Infinity are left alone.
-  //
-  // This is the CANON path only. String coercion inside `+` keeps plain
-  // JS parity ("a"+1.0 is "a1"), so it must not pick up the suffix.
   get canon() {
     const s = super.canon
     return (s.includes('.') ||

package/src/val/OpBaseVal.ts

@@ -34,9 +34,11 @@ import { FeatureVal } from './FeatureVal'
 import { hasPlace, fillPlace } from './PlaceVal'
 
 
-
-
 class OpBaseVal extends FeatureVal {
+  // An op sorts BEFORE the kinds in a conjunct: only it knows to wait
+  // for a staged operand, and a kind met first refuses it outright.
+  cjo = 48000
+
   isOp = true
 
   constructor(
@@ -79,10 +81,6 @@ class OpBaseVal extends FeatureVal {
       return fillPlace(this, peer, ctx).unify(top(), ctx)
     }
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'Op:' + this.opname(), this, peer)
-    // Declared without an initial value: every arm below assigns it, and
-    // seeding it with `this` made the two arms that stand the op read as
-    // redundant self-assignments. The arms themselves stay as they are —
-    // they mirror the dispatch switch in go/op.go arm for arm (ADR-001).
     let out: Val
 
     if (this.id == peer.id) {
@@ -95,9 +93,6 @@ class OpBaseVal extends FeatureVal {
 
     for (let arg of this.peg) {
       if (!arg.done) {
-        // Charged to the depth budget: this recurses without going
-        // through `unite`, so the counter would otherwise stay flat
-        // while the stack grows (see withDepth in unify.ts).
         const a = arg
         arg = withDepth(ctx, a, top(), () => a.unify(top(), ctx, ec(te, 'ARG')))
       }
@@ -112,12 +107,10 @@ class OpBaseVal extends FeatureVal {
       // takes the OpBaseVal arm below rather than a separate null arm.
       let result: Val = this.operate(ctx, newpeg) || this
 
-      // TODO: should be result.isOp
       if (result instanceof OpBaseVal) {
         if (peer.isTop) {
           out = this
         }
-        // TODO: should peer.isNil
         else if (peer.isNil) {
           out = makeNilErr(ctx, 'op[' + this.peg + ']', this, peer)
         }
@@ -142,24 +135,20 @@ class OpBaseVal extends FeatureVal {
       this.notdone()
       out = this.make(ctx, { peg: newpeg })
 
-      // TODO: make should handle this using ctx?
       out.site.row = this.site.row
       out.site.col = this.site.col
       out.site.url = this.site.url
       out.path = this.path
 
-      // why += 'top'
     }
     else if (peer.isNil) {
       this.notdone()
       out = peer
-      //why += 'nil'
     }
     else {
       this.notdone()
       out = new ConjunctVal({ peg: [this, peer] }, ctx)
 
-      // TODO: make should handle this using ctx?
       out.site.row = this.site.row
       out.site.col = this.site.col
       out.site.url = this.site.url
@@ -228,7 +217,6 @@ class OpBaseVal extends FeatureVal {
       undefined
     )
 
-    // TODO: refactor to use Site
     nil.path = this.path
     nil.site.url = this.site.url
     nil.site.row = this.site.row
@@ -237,7 +225,6 @@ class OpBaseVal extends FeatureVal {
     descErr(nil, ctx)
 
     if (ctx) {
-      // ctx.err.push(nil)
       ctx.adderr(nil)
     }
     else {

package/src/val/PackFuncVal.ts

@@ -1,33 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// GENERATION: `pack(data, tmpl)` (G8 phase 1,
-// docs/capability-review/g8-generation.md). One child of the result map
-// per child of `data`, each of them `tmpl` cloned at the destination.
-//
-//   names: [web, auth, billing]
-//   deploy: pack($.names, {
-//     image: "acme/" + key() + ":1.4.2"
-//     replicas: *2 | integer
-//   })
-//
-// WHY A FUNCTION AND NOT SYNTAX. A comprehension would need keywords,
-// a scoping rule, and string interpolation for the computed name; the
-// language already has functions, spread templates, and `key()`, and
-// `pack` is those three composed. A call is also DATA -- a named node
-// in the tree -- so a document that generates stays as analysable as
-// one that does not.
-//
-// KEYS ARE DATA, NOT POSITION. For a list, the strings themselves are
-// the keys (a non-string element is refused: `pack_key`); for a map,
-// its keys. Terraform's `count` keyed by index is the counter-example
-// the review names: reordering the data churns every downstream child.
-// Duplicate keys are not an error -- the colliding children unify,
-// exactly as duplicate source keys already merge.
-//
-// TOTALITY. `pack` iterates a finite, settled bag and cannot call
-// itself: the number of children it can produce is fixed by data that
-// already exists. Nothing here can recurse, which is the guarantee the
-// combinators exist to keep.
 
 import type {
   Val,
@@ -47,14 +19,7 @@ import { fillPlace } from './PlaceVal'
 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.
 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
-  // name in a list of names, packs nothing.
   const members = bagMembers(data, ctx)
 
   if (undefined === members) {
@@ -83,11 +48,6 @@ function dataKeys(data: Val | undefined, ctx: AontuContext): string[] | string {
 class PackFuncVal extends FuncBaseVal {
   isPackFunc = true
 
-  // THE STAGING RULE (G8 phase 0, see AontuContext.settle). A
-  // generator's data argument is not settled merely by being `done`
-  // once: a sibling conjunct, an include or a spread can still merge
-  // keys into it, and children generated from the half-merged bag
-  // would be missing. It fires on the settle pass and only then.
   staged = true
 
   constructor(
@@ -98,17 +58,11 @@ class PackFuncVal extends FuncBaseVal {
   }
 
 
-
   funcname() {
     return 'pack'
   }
 
 
-  // The TEMPLATE IS NOT AN ARGUMENT TO DRIVE. Driving it would resolve
-  // its `key()` at the CALL SITE -- the one position the template is
-  // never used at -- and freeze whatever else in it is path-dependent
-  // there too. The data argument is driven by `unify` below instead,
-  // one argument by hand rather than all of them by the base.
   prepare(_ctx: AontuContext, _args: Val[]) {
     return null
   }
@@ -140,24 +94,7 @@ class PackFuncVal extends FuncBaseVal {
 
     for (const key of keys) {
       const keyctx = ctx.descend(key)
-      // THE PLACEHOLDER BINDS THE SOURCE CHILD (G8 phase 3): inside a
-      // generator's template `_` is the datum this child is being made
-      // FROM. For a map that is the child's value; for a list of names
-      // it is the name, which is also the key -- so `_` and `key()`
-      // agree there, and differ the moment the data is a map.
       const source: Val = true === src?.isMap ? src.peg[key] : src.peg[keys.indexOf(key)]
-      // CLONED, never shared. A spread may share a template that holds
-      // nothing path-dependent (MapVal.spreadClone), because a spread
-      // CONSTRAINS a child that exists; a generator's template IS the
-      // child, and a child is a position. Sharing left every generated
-      // child pointing at the template's own parse-time location, which
-      // is the position the template is never used at -- visible as the
-      // site an error inside a generated child reports.
-      //
-      // A FULL INSTANCE, to the leaves (`dup`, ADR-005): a bare clone
-      // shares the inner structure of any call, preference or
-      // operation in the template, so the first child's resolution of
-      // a shared key()/ref answered for every child (BUGS.md §8, §9).
       const inst = tmpl.clone(keyctx, { dup: true })
       repathInstance(inst, inst.path)
       const child = fillPlace(inst, source, keyctx)

package/src/val/PathFuncVal.ts

@@ -1,31 +1,5 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
-// THE PATH CONSTRUCTOR (docs/design/PATHS.0.md). `path(p)` CAPTURES
-// `p` -- the one non-strict argument position in the language: every
-// other call reads its argument's value, this one reads its spelling.
-// `path($.a.b)` is the address `$.a.b` as a first-class value, not
-// the value found there; a plain reference (`$.a.b` alone) stays the
-// embedding it has always been.
-//
-// The capture happens in prepare(), which receives the argument
-// BEFORE the driving loop resolves it -- the same interception this
-// function always used, now kept instead of released: the RefVal's
-// spelling is read off its segments and the RefVal itself is never
-// driven, so no pass ever holds a resolvable reference here.
-//
-// `path()` with no argument is the path KIND (PathKindVal): the
-// vacuous constructor call is the kind, as `{}`-the-unit is to maps
-// -- see ContainerKindVal for the other half of that convention.
-//
-// A string argument is read by the ADDRESS grammar, not resolved as a
-// segment: `path("$.a")` is the same capture `path($.a)` is, and text
-// with no anchor is RELATIVE (`path("a.b")` is `path(.a.b)`, the
-// address the raw spelling captures). A COMPUTED argument -- an
-// expression, a reference to a string -- is the one shape that does
-// evaluate: the driven result converts by the same grammar at
-// resolve, which is what makes an address buildable (`refer() &
-// path("$.customers." + key())`) while a bare string still never IS
-// one (ADR-016): the conversion happens only inside this call.
 
 import type {
   Val,
@@ -110,12 +84,6 @@ class PathFuncVal extends FuncBaseVal {
         return []
       }
 
-      // The captured spelling, from a reference's segments or from a
-      // string literal read as address text. Both go through
-      // parseAddress, so what capture admits and what refer reads
-      // cannot drift. Anything else -- an expression, a reference to
-      // a string -- is left for the driving loop, and resolve
-      // converts the driven result below.
       let spelling: string | undefined
       if (true === arg.isRef) {
         spelling = captureSpelling(arg)