aontu 0.52.1 → 0.54.0

package/src/val/PackFuncVal.ts

@@ -0,0 +1,175 @@
+/* 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,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { unite } from '../unify'
+import { makeNilErr } from '../err'
+import { MapVal } from './MapVal'
+import { FuncBaseVal } from './FuncBaseVal'
+import { repathInstance } from './Val'
+import { fillPlace } from './PlaceVal'
+
+
+// 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): string[] | string {
+  const d: any = data
+
+  if (true === d?.isMap) {
+    return Object.keys(d.peg)
+  }
+
+  if (true === d?.isList) {
+    const out: string[] = []
+    for (const el of d.peg as Val[]) {
+      const e: any = el
+      // A key is a NAME, and only a string is one. A number would
+      // key by position under another spelling, which is the failure
+      // mode the data-keyed rule exists to refuse.
+      if (true !== e?.isScalar || 'string' !== typeof e.peg) {
+        return 'pack_key'
+      }
+      out.push(e.peg)
+    }
+    return out
+  }
+
+  return 'pack_data'
+}
+
+
+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(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+
+  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
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    // ONE argument is driven: the data. The template is not (see
+    // prepare above), and driveStagedArgs answers whether the data has
+    // settled -- the other half of "ready to fire".
+    const ready = this.driveStagedArgs(ctx, 1)
+
+    if (!ready || !ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const keys = dataKeys(args?.[0])
+    if ('string' === typeof keys) {
+      return makeNilErr(ctx, keys, this)
+    }
+
+    // Arity is checked at parse (funcArity), so both arguments are here.
+    const tmpl: Val = args[1]
+    const peg: Record<string, Val> = {}
+
+    const src: any = args[0]
+
+    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)
+      peg[key] = undefined === peg[key] ? child :
+        unite(keyctx, peg[key], child, 'pack')
+    }
+
+    return new MapVal({ peg }, ctx)
+  }
+
+} /* node:coverage ignore next 7 */
+
+
+export {
+  dataKeys,
+  PackFuncVal,
+}

package/src/val/PathFuncVal.ts

@@ -1,5 +1,31 @@
 /* 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,
@@ -12,9 +38,41 @@ import {
 
 import { makeNilErr } from '../err'
 
-import { NilVal } from '../val/NilVal'
-import { RefVal } from '../val/RefVal'
 import { FuncBaseVal } from './FuncBaseVal'
+import { PathVal, PathKindVal, parseAddress, textAddress } from './PathVal'
+
+
+// The address a reference SPELLS, or undefined when its segments
+// cannot spell one (a variable segment, a parent step after the first
+// named segment). Leading `.` entries in a relative ref's peg are
+// parent steps; the spelling is the same grammar refer reads, so one
+// address parser stays the single gate.
+function captureSpelling(rv: any): string | undefined {
+  const parts: string[] = []
+  let up = 0
+  let lead = true
+  for (const p of rv.peg) {
+    if ('string' !== typeof p) {
+      return undefined
+    }
+    if ('.' === p) {
+      if (!lead) {
+        return undefined
+      }
+      up++
+    }
+    else {
+      lead = false
+      parts.push(p)
+    }
+  }
+  if (0 === parts.length || (rv.absolute && 0 < up)) {
+    return undefined
+  }
+  return rv.absolute ?
+    '$.' + parts.join('.') :
+    '.'.repeat(up + 1) + parts.join('.')
+}
 
 
 class PathFuncVal extends FuncBaseVal {
@@ -42,37 +100,66 @@ class PathFuncVal extends FuncBaseVal {
 
 
   prepare(ctx: AontuContext, args: Val[]) {
-    let arg = args[0]
-
     if (0 === this.prepared) {
-      // A missing argument (`path()`) must produce an invalid-arg error
-      // value, as the Go port does -- reading .isScalar off nothing threw
-      // a TypeError that the unifier could only report as an opaque
-      // internal error. Same discipline breach, and same fix, as the one
-      // UpperFuncVal records; path() was missed in that sweep.
+      this.prepared++
+
+      const arg: any = args[0]
+
+      // The kind form: no argument to capture.
       if (null == arg) {
-        arg = makeNilErr(ctx, 'invalid-arg', this)
+        return []
       }
-      else if (arg.isScalar) {
-        arg = this.place(new RefVal({ peg: [arg], absolute: false }))
+
+      // 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)
       }
-      else if (!arg.isRef) {
-        arg = makeNilErr(ctx, 'invalid-arg', this)
+      else if (true === arg.isScalar && 'string' === typeof arg.peg) {
+        spelling = textAddress(arg.peg)
+      }
+      else {
+        return args
       }
-    }
 
-    args[0] = arg
+      if (undefined === spelling || undefined === parseAddress(spelling)) {
+        return [makeNilErr(ctx, 'path_address', this, arg)]
+      }
 
-    this.prepared++
+      return [new PathVal({ peg: spelling }, ctx)]
+    }
 
     return args
   }
 
 
   resolve(ctx: AontuContext, args: Val[]) {
-    let out = args[0] ?? makeNilErr(ctx, 'arg', this)
-
-    return out
+    if (0 === args.length) {
+      const out = new PathKindVal({}, ctx)
+      out.site = this.site
+      out.path = this.path
+      return out
+    }
+    const arg: any = args[0]
+    if (true === arg.isPath || true === arg.isNil) {
+      return arg
+    }
+    // The COMPUTED argument, driven by the loop above: a string
+    // converts by the address grammar, exactly as a literal does at
+    // capture; anything else was never a path expression.
+    if (true === arg.isScalar && 'string' === typeof arg.peg) {
+      const spelling = textAddress(arg.peg)
+      if (undefined === parseAddress(spelling)) {
+        return makeNilErr(ctx, 'path_address', this, arg)
+      }
+      return new PathVal({ peg: spelling }, ctx)
+    }
+    return makeNilErr(ctx, 'invalid-arg', this)
   }
 
 } /* node:coverage ignore next 6 */

package/src/val/PathVal.ts

@@ -0,0 +1,221 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// FIRST-CLASS PATHS (docs/design/PATHS.0.md). A PathVal is the value
+// `path(p)` captures: a tree address as DATA -- the spelling, never
+// the resolution. It is a scalar whose peg is the address string in
+// exactly the grammar `refer` reads (`$.a.b` from the root, `.b` from
+// the sibling scope, one more leading dot per parent step), which is
+// what lets a captured path meet the checking machinery unchanged.
+//
+// Meets are SYNTACTIC, by the PREFIX rule (amended, ADR-016): two
+// path values meet when one spells a prefix of the other -- same
+// anchor, the shorter's segments opening the longer's -- and the
+// result is the LONGER: a path can always be told more precisely.
+// Incomparable spellings refuse as any two unequal scalars do.
+// Resolving during a meet would make the meet depend on the value's
+// position, which is the property the staging machinery exists to
+// quarantine -- resolution stays the business of `refer`, `rel` and
+// the graph.
+//
+// The kind sits UNDER string (ScalarKindVal.KIND_PARENT), so `string`
+// admits a path value and the string constraints keep working; a
+// plain string LITERAL and a path value refuse each other, exactly as
+// the number tower's leaves do. A bare string is NEVER a path
+// (ADR-016): `path("...")` -- the call's own string argument -- is
+// the one conversion the language has.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { propagateMarks } from '../utility'
+
+import { ScalarVal } from './ScalarVal'
+import { ScalarKindVal, Path } from './ScalarKindVal'
+
+
+
+// A segment of a tree path: a map key or a list index. The same
+// grammar the rest of the engine spells keys with, and a leading digit
+// is legitimate because a list index is one.
+const ADDR_SEGMENT = /^[A-Za-z0-9_-]+$/
+
+export type Address = {
+  // Anchored at the document root (`$.a.b`) rather than at the link's
+  // own position (`.a.b`).
+  absolute: boolean
+  // Parent steps, for a relative address that climbs (`..a` is one).
+  up: number
+  // The written segments, below the anchor.
+  parts: string[]
+}
+
+
+// The address a string spells, or undefined when it does not spell
+// one. An address is a TREE PATH, in exactly the two spellings a
+// reference uses: `$.services.auth` from the root, `.auth` from the
+// link's own sibling scope. The tree is the only namespace -- which is
+// what makes a model instantiable more than once, each instance
+// resolving its relative links inside itself (ADR-014).
+export function parseAddress(s: string): Address | undefined {
+  if ('$' === s) {
+    // The whole document is not a relation's target: an address must
+    // name something with a position to be written back into.
+    return undefined
+  }
+  if (s.startsWith('$.')) {
+    const parts = s.slice(2).split('.')
+    for (const seg of parts) {
+      if (!ADDR_SEGMENT.test(seg)) {
+        return undefined
+      }
+    }
+    return { absolute: true, up: 0, parts }
+  }
+  if (!s.startsWith('.')) {
+    return undefined
+  }
+  // A relative address: the leading dot anchors it at the sibling
+  // scope, and every FURTHER leading dot is one step up from there --
+  // the same reduction a relative reference's `.` segments perform.
+  let up = 0
+  let rest = s.slice(1)
+  while (rest.startsWith('.')) {
+    up++
+    rest = rest.slice(1)
+  }
+  if ('' === rest) {
+    return undefined
+  }
+  const parts = rest.split('.')
+  for (const seg of parts) {
+    if (!ADDR_SEGMENT.test(seg)) {
+      return undefined
+    }
+  }
+  return { absolute: false, up, parts }
+}
+
+
+// The spelling string TEXT converts by, inside a `path(...)` call:
+// text that carries no anchor is RELATIVE (`"a.b"` is the address
+// `.a.b`), matching the raw form (`path(a.b)` captures `.a.b`). Only
+// the anchor is supplied -- the result still has to parse, so
+// malformed text (`""`, `"a..b"`, a bad `$` spelling) refuses as
+// before. The prefix is not applied to text that claims an anchor:
+// `"$x"` is a broken absolute address, not a relative one.
+export function textAddress(s: string): string {
+  return ('$' === s[0] || '.' === s[0]) ? s : '.' + s
+}
+
+
+// The LONGER of two addresses when one spells a prefix of the other
+// (docs/design/PATHS.0.md, amended): same anchor -- absolute or the
+// same number of parent steps -- and the shorter's segments open the
+// longer's. The meet of two path values, and of a refer's address
+// with a later path peer: a path can always be told more precisely,
+// and the more precise spelling is the result. Undefined when the two
+// are not comparable, which refuses as any two unequal scalars do.
+// Both arguments must already be valid addresses: every caller hands
+// over a PathVal peg or a refer addrsrc, and both are validated at
+// capture or conversion -- the same trust `unify`'s own address arm
+// extends (`parseAddress(p.peg) as Address`).
+export function prefixMeet(a: string, b: string): string | undefined {
+  const pa = parseAddress(a) as Address
+  const pb = parseAddress(b) as Address
+  if (pa.absolute !== pb.absolute || pa.up !== pb.up) {
+    return undefined
+  }
+  const short = pa.parts.length <= pb.parts.length ? pa : pb
+  const long = short === pa ? pb : pa
+  for (let i = 0; i < short.parts.length; i++) {
+    if (short.parts[i] !== long.parts[i]) {
+      return undefined
+    }
+  }
+  return short === pa ? b : a
+}
+
+
+
+class PathVal extends ScalarVal {
+  isPath = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super({ peg: spec.peg, kind: Path }, ctx)
+  }
+
+  // Two path values meet by the PREFIX rule (ADR-016): the longer
+  // when one opens the other, refusal otherwise. Exactly equal pegs
+  // are absorbed by unite's fast path before this runs, so the arm
+  // sees the unequal pairs; the winner carries both sides' marks, as
+  // the equal-scalar arm has always ratcheted them.
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+    if (true === p.isPath) {
+      const merged = prefixMeet(this.peg, p.peg)
+      if (undefined === merged) {
+        return makeNilErr(ctx, 'scalar_value', this, peer)
+      }
+      const out = merged === this.peg ? this : p
+      const other = out === this ? p : this
+      propagateMarks(other, out)
+      return out
+    }
+    return super.unify(peer, ctx)
+  }
+
+  // Reparses to the same VALUE: the call form is the literal syntax
+  // for this kind, so canon renders it back. The peg is already the
+  // address grammar, which the argument grammar also accepts.
+  get canon() {
+    return 'path(' + this.peg + ')'
+  }
+
+  // The super() ladder lifts a path value to its own kind, and the
+  // kind must render as `path()` -- the bare word `path` is an
+  // ordinary string. ScalarVal.superior would mint the plain
+  // ScalarKindVal, whose canon is the bare word.
+  superior() {
+    return this.place(new PathKindVal({}))
+  }
+
+} /* node:coverage ignore next 4 */
+
+
+// The path KIND, `path()`: admits every path value and defaults to
+// nothing, as `string` does. It does NOT promote (ADR-016): a bare
+// string meeting the kind refuses through the generic kind ladder,
+// exactly as `integer & "x"` does -- `path("...")` is the one string
+// conversion, and it happens at the call.
+class PathKindVal extends ScalarKindVal {
+  isPathKind = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super({ ...spec, peg: Path }, ctx)
+  }
+
+  get canon() {
+    return 'path()'
+  }
+
+} /* node:coverage ignore next 6 */
+
+
+export {
+  PathVal,
+  PathKindVal,
+}