aontu 0.53.0 → 0.55.0

package/src/sig.ts

@@ -0,0 +1,345 @@
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+
+// THE SIGNATURE REGISTRY (docs/design/SIGNATURES.0.md). The call
+// surface of the built-in functions is DECLARED, in the signature
+// syntax itself, in test/spec/signature.tsv; this module is the
+// TypeScript half of the pair that reads it. The declaration text is
+// inlined at build time (ts/src/sigdecl.ts, `make sig`) and parsed at
+// initialisation by the signature grammar -- a custom tabnas grammar,
+// the same engine the aontu grammar itself is built on -- into the
+// registry the runtime signature checker, the error-message builder,
+// the docs table and the LSP all consume. Neither port authors a
+// table: go/sig.go parses the same text with the same grammar, and
+// the shared suite round-trips every line (render(parse(line)) is the
+// line) so the two parsers cannot drift.
+//
+//   line = name '(' [ arg {',' arg} ] ')' ':' type
+//   arg  = [mode] name ['?'] ':' type
+//        | '...' name ':' ( type | '(' [mode] type {',' [mode] type} ')' )
+//   type = word {'|' word}
+//   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'
+//
+// `value` mode is unmarked; the five marked modes are the vocabulary
+// plain pseudo-TypeScript cannot say (a captured spelling is not a
+// string value). The grammar is line-oriented: the loader strips
+// comment and blank lines and parses each declaration line alone, so
+// the grammar never sees line structure.
+
+import { Tabnas } from '@tabnas/parser'
+
+import { SIGDECL } from './sigdecl'
+
+
+type ArgMode = 'value' | 'capture' | 'template' | 'trial' | 'projector' | 'text'
+
+// One group member of a rest-group argument (match's pattern/result
+// pair): a mode and a type, no name -- the group repeats.
+type GroupSig = {
+  mode: ArgMode
+  type: string
+}
+
+type ArgSig = {
+  name: string
+  mode: ArgMode
+  type: string
+  opt?: boolean
+  rest?: boolean
+  group?: GroupSig[]
+}
+
+type FuncSig = {
+  name: string
+  args: ArgSig[]
+  out: string
+}
+
+const ARG_MODES: Record<string, boolean> = {
+  capture: true, template: true, trial: true, projector: true, text: true,
+}
+
+
+// The signature grammar, as a tabnas grammar plugin. Rules: sig (the
+// line) -> args -> arg -> argtype -> type | group -> gmember. Alts
+// match at most two tokens, the engine's shape; lists loop the
+// json-grammar way (the element rule replaces itself on ',' and
+// backtracks the closer for its parent to consume).
+function sigGrammar(tn: any) {
+  tn.options({
+    fixed: {
+      token: {
+        '#OP': '(',
+        '#CP': ')',
+        '#QM': '?',
+        '#PI': '|',
+        '#DD': '...',
+      },
+    },
+    rule: { start: 'sig' },
+  })
+
+  // Parse-level validation errors, collected by the actions: the
+  // engine's own errors cover token shape, these cover word choice (a
+  // mode that is not a mode). Read after parse by parseSigLine.
+  const errs: string[] = []
+  tn.sigErrs = errs
+
+  const mode = (word: string): ArgMode => {
+    if (true !== ARG_MODES[word]) {
+      errs.push('mode:' + word)
+      return 'value'
+    }
+    return word as ArgMode
+  }
+
+  tn.grammar({
+    ref: {
+      '@sig-bo': (r: any) => {
+        r.node = { name: '', args: [], out: '' }
+        r.u.words = []
+      },
+      '@signame': (r: any) => {
+        r.node.name = String(r.o0.val)
+      },
+      '@sigargs': (r: any) => {
+        r.node.args = r.child.node
+      },
+      '@sigout': (r: any) => {
+        r.node.out = r.u.words.join('|')
+      },
+
+      '@args-bo': (r: any) => {
+        r.node = []
+      },
+
+      '@arg-bo': (r: any) => {
+        r.u.sig = { name: '', mode: 'value', type: '' }
+      },
+      '@arg-rest': (r: any) => {
+        r.u.sig.rest = true
+        r.u.sig.name = String(r.o1.val)
+      },
+      '@arg-modename': (r: any) => {
+        r.u.sig.mode = mode(String(r.o0.val))
+        r.u.sig.name = String(r.o1.val)
+      },
+      '@arg-name': (r: any) => {
+        r.u.sig.name = String(r.o0.val)
+      },
+      '@arg-opt': (r: any) => {
+        r.u.sig.opt = true
+      },
+      '@arg-done': (r: any) => {
+        const sig = r.u.sig
+        const at = r.child.node
+        if (Array.isArray(at)) {
+          sig.group = at
+          sig.type = ''
+        }
+        else {
+          sig.type = String(at)
+        }
+        r.node.push(sig)
+      },
+
+      '@argtype-bo': (r: any) => {
+        r.u.words = []
+      },
+      '@argtype-bc': (r: any) => {
+        r.node = 0 < r.u.words.length ?
+          r.u.words.join('|') : r.child.node
+      },
+
+      '@type-word': (r: any) => {
+        r.parent.u.words.push(String(r.o0.val))
+      },
+
+      '@group-bo': (r: any) => {
+        r.node = []
+      },
+      '@gm-two': (r: any) => {
+        r.u.gm = { mode: mode(String(r.o0.val)), type: String(r.o1.val) }
+      },
+      '@gm-one': (r: any) => {
+        r.u.gm = { mode: 'value', type: String(r.o0.val) }
+      },
+      '@gm-done': (r: any) => {
+        r.node.push(r.u.gm)
+      },
+    },
+
+    rule: {
+      sig: {
+        open: [
+          { s: '#TX #OP', a: '@signame', p: 'args' },
+        ],
+        close: [
+          { s: '#CL', p: 'type', a: '@sigargs' },
+          { s: '#ZZ', a: '@sigout' },
+        ],
+      },
+
+      args: {
+        open: [
+          { s: '#CP', b: 1 },
+          { p: 'arg' },
+        ],
+        close: [
+          { s: '#CP' },
+        ],
+      },
+
+      arg: {
+        open: [
+          { s: '#DD #TX', a: '@arg-rest' },
+          { s: '#TX #TX', a: '@arg-modename' },
+          { s: '#TX', a: '@arg-name' },
+        ],
+        close: [
+          { s: '#QM #CL', a: '@arg-opt', p: 'argtype' },
+          { s: '#CL', p: 'argtype' },
+          { s: '#CA', a: '@arg-done', r: 'arg' },
+          { s: '#CP', a: '@arg-done', b: 1 },
+        ],
+      },
+
+      argtype: {
+        open: [
+          { s: '#OP', p: 'group' },
+          { p: 'type' },
+        ],
+        close: [
+          {},
+        ],
+      },
+
+      type: {
+        open: [
+          { s: '#TX', a: '@type-word' },
+        ],
+        close: [
+          { s: '#PI', r: 'type' },
+          {},
+        ],
+      },
+
+      group: {
+        open: [
+          { p: 'gmember' },
+        ],
+        close: [
+          { s: '#CP' },
+        ],
+      },
+
+      gmember: {
+        open: [
+          { s: '#TX #TX', a: '@gm-two' },
+          { s: '#TX', a: '@gm-one' },
+        ],
+        close: [
+          { s: '#CA', a: '@gm-done', r: 'gmember' },
+          { s: '#CP', a: '@gm-done', b: 1 },
+        ],
+      },
+    },
+  })
+}
+
+
+let sigParser: any = undefined
+
+function makeSigParser(): any {
+  if (undefined === sigParser) {
+    sigParser = new Tabnas({ plugins: [sigGrammar] })
+  }
+  return sigParser
+}
+
+
+// Parse ONE declaration line. A malformed line is an Error: the
+// declaration is repository content, read at build and test time, so
+// failing loudly is the right shape (the round-trip suite holds the
+// gate).
+function parseSigLine(line: string): FuncSig {
+  const tn = makeSigParser()
+  tn.sigErrs.length = 0
+  const out = tn.parse(line)
+  if (0 < tn.sigErrs.length) {
+    throw new Error('signature: bad declaration ' +
+      tn.sigErrs.join(',') + ': ' + line)
+  }
+  if (null == out || '' === out.name || '' === out.out) {
+    throw new Error('signature: incomplete declaration: ' + line)
+  }
+  return out as FuncSig
+}
+
+
+// Render one argument of a signature -- the piece the LSP's
+// signatureHelp parameters share with the whole-line renderer.
+function renderSigArg(a: ArgSig): string {
+  const type = undefined === a.group ? a.type :
+    '(' + a.group.map((g: GroupSig) =>
+      ('value' === g.mode ? '' : g.mode + ' ') + g.type).join(', ') + ')'
+  return (true === a.rest ? '...' : '') +
+    ('value' === a.mode || true === a.rest ? '' : a.mode + ' ') +
+    a.name +
+    (true === a.opt ? '?' : '') +
+    ': ' + type
+}
+
+
+// Render the canonical line for a parsed signature -- the round-trip
+// twin of parseSigLine, and the one renderer every consumer (hints,
+// docs, LSP) uses.
+function renderSig(sig: FuncSig): string {
+  return sig.name + '(' +
+    sig.args.map(renderSigArg).join(', ') + ') : ' + sig.out
+}
+
+
+// Parse the whole declaration text: comment (#) and blank lines are
+// the loader's to skip, one FuncSig per remaining line, name-keyed.
+// A duplicate name is an error for the same reason a bad line is.
+function parseSigText(text: string): Record<string, FuncSig> {
+  const reg: Record<string, FuncSig> = {}
+  for (const rawline of text.split('\n')) {
+    const line = rawline.trim()
+    if ('' === line || line.startsWith('#')) {
+      continue
+    }
+    const sig = parseSigLine(line)
+    if (undefined !== reg[sig.name]) {
+      throw new Error('signature: duplicate declaration: ' + sig.name)
+    }
+    reg[sig.name] = sig
+  }
+  return reg
+}
+
+
+export type {
+  ArgMode,
+  ArgSig,
+  GroupSig,
+  FuncSig,
+}
+
+// The parsed registry, built once from the inlined declaration -- the
+// one source every consumer (the arity tables, the runtime gate, the
+// hints, the docs table, the LSP) reads. A parse failure here throws
+// at module load: the inlined text is repository content whose parse
+// the round-trip suite gates, so a failure is a build defect, not a
+// runtime condition. Twin: funcSig in go/sig.go.
+const funcSig: Record<string, FuncSig> =
+  parseSigText(SIGDECL) /* node:coverage ignore next 9 */
+
+
+export {
+  funcSig,
+  parseSigLine,
+  parseSigText,
+  renderSig,
+  renderSigArg,
+}

package/src/sigdecl.ts

@@ -0,0 +1,11 @@
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+
+// GENERATED by ts/scripts/sigdecl.cjs (`make sig`) from
+// test/spec/signature.tsv — DO NOT EDIT. The declaration is the
+// source (docs/design/SIGNATURES.0.md); ts/test/sig.test.ts asserts
+// this copy is identical with the shared file.
+
+const SIGDECL: string =
+"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number) : string\nlower(s: string|number) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t?: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\njoin(d: map|list, sep?: string) : string\n"
+
+export { SIGDECL }

package/src/siggate.ts

@@ -0,0 +1,144 @@
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+
+// THE RUNTIME SIGNATURE CHECKER (docs/design/SIGNATURES.0.md). One
+// argument gate, run by the shared function machinery
+// (FuncBaseVal.unify) just before a call resolves, when its arguments
+// are driven: for each VALUE-mode argument whose declared type is
+// scalar-kind words, the driven Val must be a concrete scalar of an
+// admitted kind. A failure refuses as `func_arg`, whose hint renders
+// the signature line and names the offending argument -- the
+// error-message builder the registry exists for.
+//
+// The gate owns exactly the argument-shape refusals that were bare
+// `invalid-arg` at the call: the case family's operand, the
+// arithmetic operands, join's separator, pick's key. Everything with
+// more meaning than a shape mismatch keeps its own code: the bag
+// arguments (`pack_data`, `each_data`, `filter_data`,
+// `aggregate_data` -- container words are not gate words), the
+// constraint atoms (not on this path at all -- their refusals ride
+// the residual), `key()` (whose level meaning `key_level` names, and
+// which is skipped here for that reason), and the capture, template,
+// trial, projector and text modes, none of which are read as values.
+//
+// What the gate refuses it must POSITIVELY identify: a concrete
+// scalar of a wrong kind, a map, a list, or a scalar KIND marker
+// where a value belongs. Anything else -- a preference, a residual, a
+// disjunct -- passes through to the builtin's own logic, which is
+// what keeps arith's unpref reading and join's deferral working.
+// Twin: sigRefuse in go/siggate.go.
+
+import type { Val } from './type'
+import { AontuContext } from './ctx'
+import { makeNilErr } from './err'
+
+import { funcSig, renderSig } from './sig'
+import type { FuncSig, ArgSig } from './sig'
+
+import {
+  BigDecimal,
+  BigInteger,
+  Float,
+  Integer,
+  Path,
+  kindSubsumes,
+} from './val/ScalarKindVal'
+
+
+// The scalar-kind words the gate enforces, each to its lattice
+// marker. A declared type is gate-checkable only when EVERY union
+// word is here: `any`, `constraint`, and the container words leave
+// the argument to the builtin.
+const SIG_KIND = new Map<string, any>([
+  ['string', String],
+  ['number', Number],
+  ['integer', Integer],
+  ['float', Float],
+  ['biginteger', BigInteger],
+  ['bigdecimal', BigDecimal],
+  ['boolean', Boolean],
+  ['path', Path],
+])
+
+
+function gateWords(type: string): any[] | undefined {
+  const out: any[] = []
+  for (const word of type.split('|')) {
+    const marker = SIG_KIND.get(word)
+    if (undefined === marker) {
+      return undefined
+    }
+    out.push(marker)
+  }
+  return out
+}
+
+
+// The declared type admits a driven Val when the Val is a concrete
+// scalar whose leaf kind is, or sits below, one of the declared
+// words -- the same walk subsumption makes, so `number` admits every
+// numeric leaf and `string` admits a path value.
+function admits(markers: any[], arg: any): boolean {
+  const leaf: any = arg.superior?.()
+  if (true !== arg.isScalar || true !== leaf?.isScalarKind) {
+    return false
+  }
+  for (const marker of markers) {
+    if (marker === leaf.peg || kindSubsumes(marker, leaf.peg)) {
+      return true
+    }
+  }
+  return false
+}
+
+
+// The gate. Answers the func_arg refusal, or undefined to let the
+// call resolve.
+function sigRefuse(
+  ctx: AontuContext, fn: any, args: Val[]
+): Val | undefined {
+  const sig: FuncSig | undefined = funcSig[fn.funcname()]
+
+  // key() reads its level off the written peg and `key_level` names
+  // what is wrong with a bad one; the gate leaves the meaning where
+  // it lives.
+  if (undefined === sig || 'key' === sig.name) {
+    return undefined
+  }
+
+  for (let i = 0; i < sig.args.length; i++) {
+    const a: ArgSig = sig.args[i]
+    if (true === a.rest) {
+      break
+    }
+    if ('value' !== a.mode) {
+      continue
+    }
+    const markers = gateWords(a.type)
+    if (undefined === markers) {
+      continue
+    }
+    const arg: any = args[i]
+    if (undefined === arg || true === arg.isNil || true !== arg.done) {
+      continue
+    }
+    const shaped = (true === arg.isScalar) ||
+      (true === arg.isMap) || (true === arg.isList) ||
+      (true === arg.isScalarKind)
+    if (shaped && !admits(markers, arg)) {
+      return makeNilErr(ctx, 'func_arg', fn, arg, undefined, {
+        func: sig.name,
+        sig: renderSig(sig),
+        arg: a.name,
+        argn: '' + (i + 1),
+        got: arg.canon,
+      })
+    }
+  }
+
+  return undefined
+} /* node:coverage ignore next 5 */
+
+
+export {
+  sigRefuse,
+}

package/src/std.ts

@@ -32,9 +32,9 @@ std: {
     protocol?: string
   })
 
-  # A node with ports. A Component that is not itself an entity is a
-  # component OF its nearest identified ancestor, which is the
-  # entity/component distinction and needs no mark of its own.
+  # A node with ports. Where a Component sits in the tree is what it
+  # is a component OF -- containment is the document's own structure
+  # and needs no mark of its own.
   Component: type({
     ports?: {&: $.std.Port}
   })
@@ -49,25 +49,86 @@ std: {
     ports?: {&: $.std.Port}
   })
 
-  # A DECLARED RELATION. "target" is what the far end must satisfy,
-  # "inverse" names the relation that must mirror it, and "acyclic"
-  # asks that the edge set have no cycle. The last two are checked
-  # AFTER unification, not by it: they are global and non-monotone ---
-  # an acyclic graph becomes cyclic when one more edge unifies in ---
-  # and no lattice citizen may be falsified by more information.
-  Relation: type({
-    target?: top
-    inverse?: string
-    acyclic?: *false | boolean
+  # (The Relation schema that used to sit here is retired with the
+  # relations: magic key, RELATIONS.0.md P2: a relation is declared
+  # by the graph atoms at its field -- rel(t) & acyclic() &
+  # inverse(name) -- and the target half is rel(t)'s flow.)
+}
+`
+
+
+const STD_VIEW = `# std/view --- the FIGURE VOCABULARY (VIEWS.0.md, "6. The view
+# document"). A view document declares its figures as data, and a
+# declaration is just a map: this is the schema for one, so a typo is
+# refused where every other mistake in an Aontu document is refused --
+# at evaluation, by unification -- rather than by the verb that reads
+# it afterwards.
+#
+#   @"std/view"
+#   @"./system.aon"
+#
+#   views: {&: $.view.Figure} & {
+#     arch: {kind: matrix, order: partition, out: "docs/arch.dsm.txt"}
+#   }
+#
+# The keys ARE the view options: the command-line flags without the
+# dashes, one vocabulary for the CLI, the library and the file. The
+# poset is not among the kinds, because a view document declares
+# figures of the ONE document it includes and the poset compares
+# several.
+#
+# EXPERIMENTAL until the distribution layer can version it by
+# canon-hash. This file carries no backtick: it is one string literal
+# per port, and Go raw strings have no escape.
+
+view: {
+
+  # One declared figure. The kind says what to draw and out says where
+  # it belongs; everything else narrows the drawing, and each option
+  # belongs to the kinds that read it.
+  Figure: type({
+    kind: doc | tree | matrix | graph | layer | sets | layers | ladder
+    out: string
+
+    # Every kind.
+    as?: text | mermaid | dot | er | svg
+    at?: string
+    maxRows?: integer & min(0)
+
+    # doc: how many levels of key to draw.
+    depth?: integer & min(0)
+
+    # tree, matrix, layer: the relation drawn. graph: the predicates
+    # kept. tree: the subtrees drawn.
+    relation?: string
+    relations?: [&: string]
+    roots?: [&: string]
+
+    # matrix.
+    order?: canon | partition
+    closure?: boolean
+
+    # graph, layer.
+    groupBy?: string
+    label?: string
+    layers?: [&: string]
+    edges?: upward | all | none
+
+    # sets, layers.
+    sets?: string
+    member?: string
+    universe?: string
+    minDegree?: integer & min(0)
+    maxCols?: integer & min(0)
+    minSize?: integer & min(0)
   })
 }
 `
 
 
-// The bundled sources, by the name a document writes. Both the bare
-// name and the `.aon` spelling resolve, because both are what an
-// author reaches for.
 export const STD_SOURCES: Record<string, string> = {
   'std/system': STD_SYSTEM,
   'std/system.aon': STD_SYSTEM,
+  'std/view': STD_VIEW,
+  'std/view.aon': STD_VIEW,
 }