aontu 0.62.0 → 0.63.0

package/src/jsonschema.ts

@@ -1,34 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// JSON SCHEMA EXPORT (the review's finding I / SUPPORT.md act 2).
-//
-// "JSON Schema's decisive 2026 advantage is not its validator ecosystem
-// -- it is that every major LLM provider's structured-output API
-// natively constrains generation to JSON Schema." Without an export,
-// Aontu cannot ride that path and then apply `vet` as the semantic gate
-// -- the hybrid an enterprise would actually deploy -- and an MCP tool's
-// `inputSchema`, which the protocol REQUIRES to be JSON Schema, cannot
-// be derived from an Aontu tool model at all (use case 09's interop
-// wall).
-//
-// THE MAPPING IS LOSSY, AND SAYS SO PER CONSTRUCT. That is the whole
-// design. Aontu's constraint algebra maps cleanly onto JSON Schema's
-// core -- bounds, patterns, lengths, enums, required and closed -- and
-// then stops: an evaluate-only `must()` is opaque by construction, an
-// exact `0d` leaf has no JSON type that preserves it, a cross-field
-// reference is not a property constraint at all, and `unique(k)` has no
-// JSON Schema spelling. A converter that dropped those silently would
-// hand its caller a schema that ADMITS MORE than the model does, which
-// is the failure mode this whole language exists to refuse. So every
-// loss is reported with its path, its construct and its reason, and
-// `--strict` turns the report into a refusal.
-//
-// It exports the UNIFIED value, not the parse: what a document MEANS is
-// what a consumer should be constrained to, and the meaning is what the
-// fixpoint produced.
-//
-// Draft 2020-12, because that is what the structured-output APIs read.
 
 import { Aontu } from './aontu'
 import { makeNilErr } from './err'
@@ -54,9 +26,6 @@ export type SchemaLoss = {
 export type SchemaVerdict = 'ok' | 'lossy' | 'error'
 
 export type SchemaReport = {
-  // `ok` everything carried; `lossy` the schema is a WEAKER statement
-  // than the model; `error` the document does not stand up and there is
-  // nothing to export.
   verdict: SchemaVerdict
   // The JSON Schema document. Empty object on `error`.
   schema: any
@@ -68,18 +37,12 @@ export type SchemaReport = {
 }
 
 export type SchemaOptions = {
-  // The subtree to export, as a path -- the same anchor `vet --at`
-  // takes, and parsed by the same walk, so `--at spec` means what it
-  // means everywhere else.
   at?: string
   // Where the document came from, so a relative `@"file"` resolves from
   // its own directory.
   path?: string
   trust?: TrustOptions
 
-  // Extensions additionally read as text (the CLI's `--text-ext`).
-  // Rides beside `trust` because it is the other half of what an
-  // include may read.
   textExt?: string[]
 }
 
@@ -102,11 +65,6 @@ function lose(ctx: Ctx, path: string[], construct: string, reason: string) {
 }
 
 
-// The JSON type for a kind marker, by the marker CLASS's name -- the
-// same load-bearing name canon renders (ScalarKindVal). `number` and
-// its four leaves all become JSON's two numeric types; the exactness of
-// `biginteger`/`bigdecimal` has no JSON type at all, which is a loss the
-// caller is told about rather than a silent widening.
 const KIND_TYPE: Record<string, string> = {
   String: 'string',
   Boolean: 'boolean',
@@ -115,17 +73,10 @@ const KIND_TYPE: Record<string, string> = {
   Float: 'number',
   BigDecimal: 'number',
   Number: 'number',
-  // A path value is its address string at the JSON boundary
-  // (docs/design/PATHS.0.md), so the projection says `string` -- the
-  // same lossy-projection rule the exact numeric leaves follow.
   Path: 'string',
 }
 
 
-// The JSON value of a concrete scalar, for `const`, `enum` and
-// `default`. An exact leaf renders through its own digits rather than
-// through binary64 -- and is reported as a loss where it is emitted,
-// because JSON's number has no exactness to receive it.
 function scalarJson(v: any): any {
   if (v.isBigInteger) {
     return Number(v.peg)
@@ -149,9 +100,6 @@ function scalarType(v: any): string {
 }
 
 
-// The constraint residual's atoms, onto JSON Schema's keywords. The
-// three that map exactly (bounds, pattern, count) go across; the two
-// that cannot (`must`, `unique(k)`) are reported.
 function fromConstraint(ctx: Ctx, path: string[], c: any): any {
   const out: any = {}
 
@@ -165,9 +113,6 @@ function fromConstraint(ctx: Ctx, path: string[], c: any): any {
     out.type = 'number'
   }
 
-  // Bounds. An OPEN endpoint is JSON Schema's exclusive form, which is
-  // a keyword of its own in 2020-12 rather than the boolean flag draft-4
-  // used.
   if (null != c.lo) {
     out[c.lo.open ? 'exclusiveMinimum' : 'minimum'] = scalarJson(c.lo.v)
   }
@@ -181,11 +126,6 @@ function fromConstraint(ctx: Ctx, path: string[], c: any): any {
     out.not = { enum: c.neqs.map(scalarJson) }
   }
 
-  // Patterns. Aontu DEFINES its portable subset (`re`'s abbreviations
-  // mean the same in both ports); every member of that subset is also
-  // an ECMA-262 regular expression, which is what JSON Schema's
-  // `pattern` is read as, so this crosses without translation. More
-  // than one pattern needs `allOf`: `pattern` is a single keyword.
   if (1 === c.res.length) {
     out.pattern = c.res[0].src
   }
@@ -193,10 +133,6 @@ function fromConstraint(ctx: Ctx, path: string[], c: any): any {
     out.allOf = c.res.map((r: any) => ({ pattern: r.src }))
   }
 
-  // A COUNT is a length or a size depending on what is counted, and the
-  // residual does not always know which. Where the domain says string,
-  // it is minLength/maxLength; otherwise the container keywords, since
-  // a count atom on a container is what `length` overwhelmingly means.
   if (null != c.count) {
     const lo = null == c.count.lo ? undefined : scalarJson(c.count.lo.v)
     const hi = null == c.count.hi ? undefined : scalarJson(c.count.hi.v)
@@ -236,28 +172,6 @@ function fromConstraint(ctx: Ctx, path: string[], c: any): any {
 }
 
 
-// The exporter proper. Every arm answers a schema; the ones that cannot
-// answer honestly report a loss and fall back to `{}`, which admits
-// anything -- the safe direction for a document that will be checked
-// again by `vet`, and the direction the loss report exists to make
-// visible.
-// NO DEFENSIVE GUARD ON `v`. Every caller walks a bag's own children
-// and a bag holds Vals, so a non-Val here is not a degenerate input,
-// it is a bug in this file -- and an unreachable `if` is a branch arm
-// the ADR-002 gate counts and no `node:coverage ignore` suppresses
-// (the marker drops LINES, not branches). Go's twin keeps its `nil ==
-// v` arm because a missing map key there yields a typed nil rather
-// than an absent property.
-// DEPRECATION IS AN ANNOTATION, and 2020-12 has one: `deprecated`.
-// The export used to drop the whole record in SILENCE -- no keyword,
-// and no loss line even under --strict -- which is the one thing the
-// verb's own contract says it never does (use-cases/BUGS.md §56).
-//
-// The boolean crosses faithfully. The record's STRINGS (msg, use,
-// since) have no home in 2020-12, so they are reported as a loss
-// rather than invented into `description`: this exporter emits no
-// `description` anywhere, and quietly making it mean "deprecation
-// note" would be a mapping a consumer cannot undo.
 function fromVal(ctx: Ctx, path: string[], v: any): any {
   const out = fromValInner(ctx, path, v)
 
@@ -278,18 +192,10 @@ function fromVal(ctx: Ctx, path: string[], v: any): any {
 }
 
 
-// The record's text keys -- the ones with nothing to carry them.
-// `DEPRECATION_KEYS` in DeprecateFuncVal.ts is the authority on what a
-// record may hold; this is that list, and a key added there without a
-// JSON Schema home belongs here too.
 const DEPRECATION_TEXT = ['msg', 'use', 'since']
 
 
 function fromValInner(ctx: Ctx, path: string[], v: any): any {
-  // A preference is its inner value plus a DEFAULT. JSON Schema's
-  // `default` is annotation rather than constraint -- it does not
-  // validate -- which is exactly what a preference is when something
-  // else supplies the value.
   if (true === v.isPref) {
     const inner = fromVal(ctx, path, v.peg)
     const gen = generated(v.peg)
@@ -304,12 +210,6 @@ function fromValInner(ctx: Ctx, path: string[], v: any): any {
     return fromConstraint(ctx, path, v)
   }
 
-  // A SIZING RESIDUE is a container and its own sizing atom, kept
-  // together because more members could still change the atom's reading
-  // (use-cases/BUGS.md §16). Both halves are exportable and both must
-  // be: the container gives the shape, the atom gives `uniqueItems` and
-  // the length keywords, and a walk that saw only "a conjunct" would
-  // report the whole field as unresolved and admit anything.
   const residue = sizingResidue(v)
   if (undefined !== residue) {
     return {
@@ -334,10 +234,6 @@ function fromValInner(ctx: Ctx, path: string[], v: any): any {
         'this leaf exists for cannot be carried; the schema says ' +
         '"' + t + '" and a consumer may round')
     }
-    // KIND_TYPE is TOTAL over the kinds a marker can carry, so there is
-    // no miss to fall back from -- and a fallback that cannot be taken
-    // is a branch arm the coverage gate counts. Go's twin keeps its
-    // empty-map arm, which its own ignore mechanism can carry.
     return { type: t }
   }
 
@@ -358,9 +254,6 @@ function fromValInner(ctx: Ctx, path: string[], v: any): any {
     return { const: scalarJson(v), type: scalarType(v) }
   }
 
-  // Everything else is residue: a reference that did not resolve, a
-  // function or operator still waiting, a nil. None of them is a
-  // property constraint, and guessing one would be inventing a promise.
   lose(ctx, path, residueName(v),
     'this is not a value yet, so there is nothing to constrain a ' +
     'consumer to; the schema admits anything here')
@@ -380,10 +273,6 @@ function residueName(v: any): string {
 // generate. Used for `default` and for `enum` members: both are VALUES
 // in the schema, so a member that is itself a shape has none to give.
 function generated(v: any): any {
-  // No try/catch: a collecting context RECORDS a failed generation on
-  // itself instead of throwing, which is the whole point of the mode.
-  // Neither `vet` nor the Go twin (`schemaGenerated`) wraps this
-  // either, and an untakeable catch is a branch arm the gate counts.
   const a0 = new Aontu()
   const ctx = a0.ctx({ collect: true })
   const out = v.gen(ctx)
@@ -391,10 +280,6 @@ function generated(v: any): any {
 }
 
 
-// A disjunction of CONCRETE members is an enum -- the shape a
-// structured-output API constrains best. Anything else is `anyOf`. A
-// preferred member contributes the `default` either way, which is how
-// `*"a"|"b"|"c"` reaches a provider as a defaulted enum.
 function fromDisjunct(ctx: Ctx, path: string[], v: any): any {
   const members: any[] = v.peg
   let def: any = undefined
@@ -492,8 +377,6 @@ function fromList(ctx: Ctx, path: string[], v: any): any {
     return out
   }
 
-  // A written list literal is a TUPLE: position by position, and no
-  // more. 2020-12 spells that `prefixItems` plus `items: false`.
   return {
     type: 'array',
     prefixItems: els.map((el: any, i: number) =>
@@ -509,12 +392,6 @@ export function jsonSchema(src: string, options?: SchemaOptions): SchemaReport {
   const opts = options ?? {}
   const aontu = new Aontu(includeOpts(opts))
 
-  // COLLECT MODE, so a syntax error arrives on the context rather than
-  // as a throw -- the same failure Go's `parseEntry` hands back as an
-  // error, reached by the branch below. No try/catch here for the same
-  // reason `vet` has none: the mode exists so the failure can be
-  // reported rather than escape, and a catch that cannot be entered is
-  // a branch arm the ADR-002 gate counts.
   const actx = aontu.ctx({ collect: true })
   const root: any = aontu.unify(src, { path: opts.path, collect: true }, actx)
 

package/src/keyorder.ts

@@ -1,47 +1,7 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/*
- * THE ONE MAP-KEY ORDER, shared by every site that emits keys.
- *
- * Map key order is not meaningful in unification, so both ports sort to
- * make output independent of insertion and unification order. The order
- * they sort into has to be the SAME order, and it was not.
- *
- * JavaScript compares strings by UTF-16 CODE UNIT. An astral character is
- * stored as a surrogate pair beginning D800-DBFF, so `<` puts it BEFORE
- * every character in U+E000-U+FFFF -- ahead of the private use area, of
- * U+FFFD, of U+FFFF. Go sorts map keys as UTF-8 bytes, which is code
- * POINT order, so it puts the astral character last. The two agree on
- * everything below U+D800 and disagree above U+DFFF, which is why this
- * survived: the shared suite had no key above the BMP at all, and three
- * separate comments in the tree asserted the ports already agreed.
- *
- * CODE POINT ORDER WINS, and not merely because Go had it. Go's
- * `generate()` returns a native map, so a consumer's own `json.Marshal`
- * sorts byte-wise no matter what this engine chooses -- picking UTF-16
- * order would leave the TypeScript output disagreeing with what a Go
- * consumer produces from the same document.
- *
- * NOT Buffer.compare, which would be the obvious shortcut. A lone
- * surrogate has no valid UTF-8 encoding, so Buffer.from replaces it with
- * U+FFFD and two DISTINCT keys compare equal -- reintroducing exactly the
- * insertion-order dependence the sort exists to remove. Iterating code
- * points keeps distinct keys distinct.
- */
 
-
-/**
- * Compare two map keys by Unicode CODE POINT.
- *
- * `String.prototype[Symbol.iterator]` yields whole code points, pairing
- * surrogates, so this is a plain lexicographic compare of code point
- * sequences -- the order Go's UTF-8 byte sort produces.
- */
 function cmpCodePoint(a: string, b: string): number {
-  // Fast path: identical strings, and the common all-BMP case where the
-  // two orders coincide, still walk the iterator -- but the loop exits at
-  // the first differing code point, so it is one pass over the shared
-  // prefix rather than any conversion or allocation.
   const ai = a[Symbol.iterator]()
   const bi = b[Symbol.iterator]()
 
@@ -49,8 +9,6 @@ function cmpCodePoint(a: string, b: string): number {
     const x = ai.next()
     const y = bi.next()
 
-    // A prefix sorts before the string it is a prefix of, and two equal
-    // strings compare 0 -- the same rule a byte compare gives.
     if (x.done) {
       return y.done ? 0 : -1
     }