aontu 0.29.0 → 0.30.2

package/src/aontu.ts

@@ -0,0 +1,218 @@
+/* Copyright (c) 2021-2025 Richard Rodger, MIT License */
+
+import type { Val, AontuOptions } from './type'
+
+import { Lang } from './lang'
+import { Unify } from './unify'
+import { AontuContext, AontuContextConfig } from './ctx'
+import { MapVal } from './val/MapVal'
+import { formatExplain } from './utility'
+import { makeNilErr, AontuError } from './err'
+
+
+
+class Aontu {
+  opts: AontuOptions
+  lang: Lang
+
+
+  constructor(popts?: AontuOptions) {
+    this.opts = popts ?? {}
+    this.lang = new Lang(this.opts)
+  }
+
+
+  // Create a new context.
+  ctx(cfg?: AontuContextConfig): AontuContext {
+    cfg = cfg ?? {}
+    const ac = new AontuContext(cfg)
+    return ac
+  }
+
+
+  // Parse source into a matching Val AST, not yet unified.
+  parse(src: string, opts?: AontuOptions, ac?: AontuContext): Val | undefined {
+    let out: Val | undefined
+    let errs: any[] = []
+
+    if (null == src) {
+      src = ''
+    }
+
+    ac = ac ?? this.ctx()
+    ac.addopts({ ...(opts ?? {}), src })
+
+    if ('string' !== typeof src) {
+      out = makeNilErr(ac, 'parse_bad_src')
+      errs.push(out)
+    }
+
+    if (0 === errs.length) {
+      out = runparse(src, this.lang, ac)
+      out.deps = ac.deps
+      ac.root = out
+    }
+
+    handleErrors(errs, out, ac)
+
+    return out
+  }
+
+
+  // Unify source or Val, returning a fully unified Val.
+  unify(src: string | Val, opts?: AontuOptions, ac?: AontuContext | any): Val {
+    let out: Val | undefined
+    let errs: any[] = []
+
+    ac = ac ?? this.ctx()
+    ac.addopts({ ...(opts ?? {}), src })
+
+    let pval: Val | undefined
+
+    if (null == src) {
+      src = ''
+    }
+
+    if ('string' === typeof src) {
+      pval = this.parse(src, undefined, ac)
+    }
+    else if (src && src.isVal) {
+      pval = src
+    }
+    else {
+      out = makeNilErr(ac, 'unify_no_src')
+      errs.push(out)
+    }
+
+    if (null != pval && 0 === errs.length) {
+      let uni = new Unify(pval, this.lang, ac, src)
+      errs = uni.err
+
+      out = uni.res
+
+      if (null == out) {
+        out = makeNilErr(ac, 'unify_no_res')
+        if (0 === errs.length) {
+          errs = [out]
+        }
+      }
+
+      out.deps = pval.deps
+      out.err = errs
+      ac.root = out
+    }
+
+    handleErrors(errs, out, ac)
+
+    return out as Val
+  }
+
+
+  // Generate output structure from source, which must parse and fully unify.
+  generate(src: string, opts?: any, ac?: AontuContext): any {
+    try {
+      let out = undefined
+
+      ac = ac ?? this.ctx()
+      ac.addopts({ ...(opts ?? {}), src })
+
+      let pval = this.parse(src, undefined, ac)
+
+      if (undefined !== pval && 0 === pval.err.length) {
+
+        let uval = this.unify(pval, undefined, ac)
+
+        if (undefined !== uval && 0 === uval.err.length) {
+
+          out = uval.isNil ? (ac.adderr(uval as any), undefined) : uval.gen(ac as any)
+
+          if (0 < ac.err.length) {
+            if (!ac.collect) {
+              throw new AontuError(ac.errmsg(), ac.err)
+            }
+            out = undefined
+          }
+        }
+      }
+
+      return out
+    }
+    catch (err: any) {
+      if (err instanceof AontuError || true === err.aontu) {
+        throw err
+      }
+      const unex = new AontuError('Aontu: unexpected error: ' + err.message)
+      Object.assign(unex, err)
+      unex.stack = err.stack
+      throw unex
+    }
+  }
+}
+
+
+// Either throw an exception or add collected errors to result.
+function handleErrors(errs: any[], out: Val | undefined, ac: AontuContext) {
+
+  errs.map((err: any) => ac.adderr(err))
+
+  if (out) {
+    out.err.map((err: any) => ac.adderr(err))
+  }
+
+  if (0 < ac.err.length) {
+    if (ac.collect) {
+      if (out) {
+        out.err = ac.err
+      }
+    }
+    else {
+      throw new AontuError(ac.errmsg(), ac.err)
+    }
+  }
+}
+
+
+// Perform parse of source code (minor customizations over Lang.parse).
+function runparse(src: string, lang: Lang, ctx: AontuContext): Val {
+  const popts = {
+    // src: ctx.src,
+    deps: ctx.deps,
+    fs: ctx.fs,
+    path: ctx.opts.path
+  }
+  let val
+
+  const tsrc = src.trim().replace(/^(\n\s*)+/, '')
+
+  if ('string' === typeof src && '' !== tsrc) {
+    val = lang.parse(src, popts)
+  }
+
+  if (undefined === val) {
+    val = new MapVal({ peg: {} })
+  }
+
+  return val
+}
+
+
+const util = {
+  runparse,
+}
+
+
+export {
+  Aontu,
+  AontuOptions,
+  AontuContext,
+  AontuError,
+
+  Val,
+  Lang,
+  runparse,
+  util,
+  formatExplain
+}
+
+
+export default Aontu

package/src/ctx.ts

@@ -0,0 +1,201 @@
+/* Copyright (c) 2021-2025 Richard Rodger, MIT License */
+
+
+import type { Val, FST, AontuOptions } from './type'
+
+import { DEFAULT_OPTS } from './type'
+
+
+import { MapVal } from './val/MapVal'
+import { ListVal } from './val/ListVal'
+import { NilVal } from './val/NilVal'
+
+
+import {
+  descErr
+} from './err'
+
+
+
+type AontuContextConfig = {
+  cc?: number
+  err?: any[] // Omit<NilVal[], "push">
+  explain?: any[]
+  fs?: any
+  path?: string[]
+  root?: Val
+  seen?: Record<string, number>
+  seenI?: number
+  src?: string
+  srcpath?: string
+  vars?: Record<string, Val>
+  vc?: number
+  collect?: boolean
+  opts?: AontuOptions
+  deps?: Record<string, any>
+}
+
+
+class AontuContext {
+  root?: Val   // Starting Val, root of paths.
+  path: string[]  // Path to current Val.
+  vc: number  // Val counter to create unique val ids.
+  cc: number = -1
+  vars: Record<string, Val> = {}
+  src?: string
+  fs?: FST
+
+  seenI: number
+  seen: Record<string, number>
+
+  collect: boolean
+
+  // errlist: Omit<NilVal[], "push">  // Nil error log of current unify.
+  err: any[]
+  explain: any[] | null
+
+  // TODO: separate options and context!!!
+  srcpath?: string
+
+  deps: Record<string, any>
+  opts: AontuOptions
+
+  _pathstr: string | undefined
+
+
+  constructor(cfg: AontuContextConfig) {
+    this.root = cfg.root
+    this.path = [...(cfg.path ?? [])]
+    this.src = cfg.src
+
+    this.collect = cfg.collect ?? null != cfg.err
+
+    this.err = cfg.err ?? []
+    this.explain = cfg.explain ?? null
+
+    this.fs = cfg.fs ?? null
+
+    // Multiple unify passes will keep incrementing Val counter.
+    this.vc = null == cfg.vc ? 1_000_000_000 : cfg.vc
+
+    this.cc = null == cfg.cc ? this.cc : cfg.cc
+
+    this.vars = cfg.vars ?? this.vars
+    this.seenI = cfg.seenI ?? 0
+    this.seen = cfg.seen ?? {}
+
+    this.srcpath = cfg.srcpath ?? undefined
+
+    this.deps = cfg.deps ?? {}
+
+    this.opts = DEFAULT_OPTS()
+    this.addopts(cfg.opts)
+  }
+
+
+  clone(cfg: {
+    root?: Val,
+    path?: string[],
+    err?: any[],
+    explain?: any[]
+  }): AontuContext {
+    const ctx = Object.create(this)
+    ctx.path = cfg.path ?? this.path
+    ctx.root = cfg.root ?? this.root
+    ctx.var = Object.create(this.vars)
+
+    ctx.err = cfg.err ?? ctx.err
+    ctx.explain = cfg.explain ?? ctx.explain
+
+    ctx._pathstr = undefined
+
+    return ctx
+  }
+
+  descend(key: string): AontuContext {
+    return this.clone({
+      root: this.root,
+      path: this.path.concat(key),
+    })
+  }
+
+
+  addopts(opts?: AontuOptions) {
+    if (null != opts) {
+      Object.assign(this.opts, opts)
+    }
+
+    this.collect = (this.opts.collect ?? null != this.opts.err) ?? this.collect
+    this.err = this.opts.err ?? this.err
+    this.fs = this.opts.fs ?? this.fs
+    this.explain = this.opts.explain ?? this.explain
+
+    this.src = ('string' === typeof this.opts.src ? this.opts.src : undefined) ?? this.src
+
+    // TODO: rename srcpath to file
+    this.srcpath = this.opts.path ?? this.srcpath
+  }
+
+
+  adderr(err: NilVal) {
+    if (null != err && err.isNil) {
+      if (null == err.primary) {
+        err.primary = err
+      }
+
+      if (!this.err.includes(err)) {
+        this.err.push(err)
+      }
+      if (null == err.msg || '' == err.msg) {
+        descErr(err, this)
+      }
+    }
+  }
+
+
+  errmsg() {
+    // return this.errlist
+    return this.err
+      .map((err: any) => err?.msg)
+      .filter(msg => null != msg)
+      .join('\n------\n')
+  }
+
+
+  find(path: string[]): Val | undefined {
+    let node: Val | undefined = this.root
+    let pI = 0
+    for (; pI < path.length; pI++) {
+      let part = path[pI]
+
+      if (node instanceof MapVal) {
+        node = node.peg[part]
+      }
+      else if (node instanceof ListVal) {
+        node = node.peg[part]
+      }
+      else {
+        break;
+      }
+    }
+
+    if (pI < path.length) {
+      node = undefined
+    }
+
+    return node
+  }
+
+
+  get pathstr() {
+    return this._pathstr ??
+      (this._pathstr = this.path.map(p => p.replaceAll('.', '\\.')).join('.'))
+  }
+}
+
+
+
+export {
+  AontuContext,
+  AontuContextConfig
+}

package/src/err.ts

@@ -0,0 +1,172 @@
+/* Copyright (c) 2021-2025 Richard Rodger, MIT License */
+
+
+import { util } from 'jsonic'
+
+import { Val, ErrContext } from './type'
+
+import { AontuContext } from './ctx'
+
+import { NilVal } from './val/NilVal'
+
+import { hints } from './hints'
+
+
+const { errmsg } = util
+
+
+function getHint(why: any): string | undefined {
+  if (hints[why]) {
+    return hints[why]
+  }
+
+  return undefined
+}
+
+
+function makeNilErr(
+  ctx?: AontuContext,
+  why?: any,
+  av?: Val,
+  bv?: Val,
+  attempt?: string
+): NilVal {
+  const nilval = NilVal.make(ctx, why, av, bv, attempt)
+  return nilval
+}
+
+
+// TODO: move to utility?
+function descErr<NILS extends NilVal | NilVal[]>(
+  err: NILS | any,
+  errctx?: ErrContext,
+): any {
+  if (err?.isNil) {
+    if (null == err.msg || '' === err.msg) {
+      let v1: any = err.primary
+      let v2: any = err.secondary
+
+      let v1src = resolveSrc(v1, errctx)
+      let v2src = resolveSrc(v2, errctx)
+
+      let path = ['$', ...err.path].filter((p: any) => null != p && '' != p)
+
+      let valpath = (0 < path.length ? path.join('.') : '')
+      let attempt = null != err.attempt ? err.attempt : (null == v2 ? 'resolve' : 'unify')
+
+      err.msg = [
+        errmsg({
+          color: { active: true },
+          name: 'aontu',
+          code: err.why,
+          txts: {
+            msg: 'Cannot ' +
+              attempt +
+              ' value' + (null == v2 ? '' : 's') +
+              ' at path ' + valpath,
+            hint: getHint(err.why)
+          }
+        }),
+
+        '\n',
+
+        (null != v1 && errmsg({
+          // TODO: color should come from jsonic config
+          color: { active: true, line: '\x1b[34m' },
+          txts: {
+            msg: 'Cannot ' + attempt + ' value: ' + v1.canon +
+              (null == v2 ? '' : ' with value: ' + v2.canon), // + ' #' + err.id,
+            site: ''
+          },
+          smsg: 'value was: ' + v1.canon,
+          file: resolveFile(v1.site.url),
+          src: v1src,
+          row: v1.site.row,
+          col: v1.site.col,
+        })),
+
+        (null != v2 && errmsg({
+          // TODO: color should come from jsonic config
+          color: { active: true, line: '\x1b[34m' },
+          txts: {
+            msg: 'Cannot ' + attempt + ' value: ' + v2.canon +
+              ' with value: ' + v1.canon, // + ' #' + err.id,
+            site: ''
+          },
+          smsg: 'value was: ' + v2.canon,
+          file: resolveFile(v2.site.url),
+          src: v2src,
+          row: v2.site.row,
+          col: v2.site.col,
+        })),
+
+
+      ]
+        .filter((n: any) => null != n && false !== n)
+        .join('\n')
+
+        // TODO: update jsonic errmsg to avoid multiple empty lines
+        .replace(/\n\n/g, '\n')
+
+    }
+    return err
+  }
+  else {
+    return err.map((n: any) => descErr(n, errctx))
+  }
+}
+
+function resolveFile(url: string | undefined) {
+  const cwd = process.cwd()
+  let out = url?.replace(cwd + '/', '') ?? '<no-file>'
+  out = out === cwd || '' === out ? '<no-file>' : out
+  return out
+}
+
+
+function resolveSrc(v: Val, errctx?: ErrContext) {
+  let src: string | undefined = undefined
+
+  if (null != v?.site.url) {
+    try {
+      const fileExists = errctx?.fs?.existsSync(v.site.url)
+      if (fileExists) {
+        src = errctx?.fs?.readFileSync(v.site.url, 'utf8') ?? undefined
+      }
+    }
+    catch (fe: any) {
+      // ignore as more important to report original error
+    }
+  }
+
+  if (errctx && (undefined == src || '' === src)) {
+    src = errctx.src ?? ''
+  }
+
+  return src
+}
+
+
+class AontuError extends Error {
+  aontu = true
+
+  constructor(msg: string, errs?: NilVal[]) {
+    super(msg)
+    this.name = this.constructor.name
+    this.errs = () => errs ?? []
+
+    this.stack = this.stack?.split('\n')
+      .filter(line => !line.match(/aontu\/(src|dist)\//))
+      .join('\n')
+  }
+
+  errs: () => NilVal[]
+}
+
+
+export {
+  getHint,
+  makeNilErr,
+  descErr,
+  AontuError,
+}

package/src/hints.ts

@@ -0,0 +1,119 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+/**
+ * Error code hints for Aontu unification errors.
+ *
+ * Each key is an error code that can be passed to makeNilErr.
+ * Each value is a human-readable explanation of what the error means.
+ */
+
+const hints: Record<string, string> = {
+
+  scalar_value:
+    'Literal scalar values of the same kind can only unify if they are\n' +
+    'exactly equal.' +
+    '\n \nExamples:\n' +
+    '  1 & 1   -> 1    # Does unify (equal Integers);\n' +
+    '  a & a   -> a    # Does unify (equal Strings);\n' +
+    '  1 & 2   -> nil  # Does not unify (unequal Integers);\n' +
+    '  1 & 1.0 -> nil  # Does not unify (kinds: Integer & Number).',
+
+  scalar_kind:
+    'Literal scalar values of different kinds cannot unify.' +
+    '\n \nExamples:\n' +
+    '  1 & 1   -> 1    # Does unify (equal Integers);\n' +
+    '  1 & a   -> nil  # Does not unify (Kinds: Integer & String);\n' +
+    '  1 & 1.0 -> nil  # Does not unify (kinds: Integer & Number).',
+
+  nil_gen:
+    'The nil value was present after unification, and nil cannot be\n' +
+    'generated because nil is not a literal value.',
+
+  no_gen:
+    'This value was present after unification, and cannot be generated\n' +
+    'because it is not a literal value.',
+
+
+  // TODO: extend errors to have details so we can name the key
+  mapval_required: 'This map value is required.',
+
+  mapval_no_gen:
+    'This value was present after unification, and cannot be generated\n' +
+    'because it is not a literal value.',
+
+  listval_required: 'This list element is required.',
+
+  listval_no_gen:
+    'This list element was present after unification, and cannot be generated\n' +
+    'because it is not a literal value.',
+
+  unknown_function:
+    'This function name is not recognized.',
+
+  literal_nil:
+    'A literal nil cannot unify with any other value.',
+
+
+  // Parsing errors
+  'parse_bad_src': 'Invalid source provided for parsing. The source must be a non-empty string.',
+
+  // Unification errors
+  'unify_no_src': 'No source provided for unification. Cannot unify without source values.',
+  'unify_no_res': 'Unification produced no result. The values could not be unified.',
+  'unite': 'Failed to unite two values. The values are incompatible and cannot be unified.',
+  'cycle': 'Circular reference detected during unification. The unification process encountered a cycle.',
+  'internal': 'Internal error during unification. This indicates an unexpected error in the unification process.',
+
+  // Type mismatch errors
+
+  'scalar-type': 'Scalar type mismatch. The scalar types are incompatible.',
+  'no-scalar-unify': 'Cannot unify scalar values. The scalar values have incompatible types.',
+  'not-scalar-type': 'Expected a scalar type but got a non-scalar type.',
+  'map': 'Type mismatch: expected a map value but got a different type.',
+  'list': 'Type mismatch: expected a list value but got a different type.',
+
+  // Argument errors
+  'arg': 'Missing required argument. A function requires an argument but none was provided.',
+  'invalid-arg': 'Invalid argument provided. The argument does not match the expected type or format.',
+  'no_first_arg': 'Missing first argument. The function requires a first argument but none was provided.',
+
+  // Variable errors
+  'unknown_var': 'Unknown variable reference. The variable has not been defined.',
+  'invalid_var_kind': 'Invalid variable kind. The variable type does not match the expected kind.',
+
+  // Path and reference errors
+  path_cycle: 'Path cycle detected. The path contains a circular reference.',
+  'ref': 'Reference resolution failed. Unable to resolve the reference to a value.',
+
+  // Closure and state errors
+  'closed': 'Cannot add to closed structure. The map or list is closed and does not accept new keys/elements.',
+  'required_listelem': 'Required list element is missing. A non-optional list element has no value.',
+
+  // Junction errors (disjunction/conjection)
+  '|:empty': 'Empty disjunction. The disjunction has no valid alternatives.',
+  '|:empty-dist': 'Empty disjunction distribution. All alternatives in the disjunction are invalid.',
+
+  // Function errors (dynamic patterns)
+  'func': 'Function operation failed. See the specific function name for details.',
+  'make': 'Failed to create a new value. The make operation could not construct the value.',
+  'resolve': 'Failed to resolve a value. The resolution process could not find or compute the value.',
+  'operate': 'Operation failed. The operation could not be performed on the given values.',
+
+  // Operator errors (dynamic patterns)
+  'op': 'Operator operation failed. See the specific operator name for details.',
+
+  // Close operation
+  'close': 'Failed to close structure. The structure could not be closed.',
+
+  // Dynamic patterns (these serve as prefixes)
+  'func:': 'Function error: ',
+  'op:': 'Operator error: ',
+  'var[': 'Variable type error: ',
+  'ref[': 'Reference error: ',
+  'op[': 'Operator value error: ',
+}
+
+
+export {
+  hints,
+}