aontu 0.50.1 → 0.52.0

package/dist/exactjson.js

@@ -0,0 +1,228 @@
+"use strict";
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exactJSON = exactJSON;
+/*
+ * D9 -- THE EXACT JSON EMITTER.
+ *
+ * `generate()` returns NATIVE values, and once a document opts into the
+ * exact leaves two of them are not things `JSON.stringify` can write: a
+ * biginteger generates as a native `bigint`, and a bigdecimal generates
+ * as a `Decimal`. `JSON.stringify` THROWS on a bigint ("Do not know how
+ * to serialize a BigInt") and a `replacer` cannot rescue it, because a
+ * replacer may only return another *value* -- everything it returns that
+ * is not already a JSON primitive gets quoted, so the exact digits could
+ * only come back as a JSON *string*, which is a different document.
+ *
+ * JSON itself was never the obstacle. A JSON number is arbitrary-
+ * precision decimal TEXT: `{"x":9007199254740993}` is a perfectly legal
+ * document that every conforming parser reads, and Go's `encoding/json`
+ * already emits exactly that for a `*big.Int`. Only JavaScript's
+ * serialiser stands in the way, so aontu ships its own.
+ *
+ * WHY THIS IS PUBLIC API and not a CLI internal: D9 promises that an
+ * exact value reaches JSON as exact digits. A library consumer whose
+ * document contains `0d9007199254740993` has no other supported way to
+ * keep that promise -- hiding the only implementation behind the command
+ * line would leave the contract unfulfillable from the library. The
+ * `aontu` CLI consumes this same export (with `indent`), and so does the
+ * shared suite's byte-exact `gens` mode, so there is exactly one set of
+ * bytes to keep in step with the Go port.
+ *
+ * PARITY WITH GO. The output must match Go's
+ * `json.Encoder` + `SetEscapeHTML(false)` (see specGens in
+ * go/spec_test.go) byte for byte:
+ *
+ *   - Key order is the order `generate()` produced. Both ports already
+ *     sort map keys (see the entries sort in BagVal.gen; Go's encoder
+ *     sorts map keys), so neither has to sort again here.
+ *   - Strings keep JavaScript's escaping, which is what the `gens` mode
+ *     settled on when it turned Go's HTML escaping OFF so that `<`, `>`
+ *     and `&` stay literal in both ports. U+2028/U+2029 are the one
+ *     place JS and Go disagree by default -- Go escapes them, JS does
+ *     not -- so they are escaped here too, which is both legal JSON and
+ *     the safer output (it can be embedded in a JavaScript source).
+ *   - Numbers keep JavaScript's `Number.prototype.toString` form, which
+ *     is already what Go's encoder produces: fixed notation inside
+ *     [1e-6, 1e21) and an unpadded, always-signed exponent outside it
+ *     (`1e+21`, `1e-7`).
+ *   - A bigint writes its digits; a Decimal writes its plain digit form
+ *     (`1000.0`, `0.1`, `-1.5`) -- no `0d` marker, since that belongs to
+ *     canon and is not JSON, but an integral bigdecimal keeps its `.0`
+ *     so the JSON still shows a decimal. Go's `*Decimal.MarshalJSON`
+ *     mirrors this.
+ *
+ * NOTE that byte-exact output CANNOT check the other half of D9: an
+ * integral bigdecimal and a biginteger can serialise to different text,
+ * but a biginteger and an ordinary integer serialise to the SAME text
+ * while `generate()` returned the wrong runtime type. Canon pins the AST
+ * kind, `gens` pins these bytes, and only the per-port API tests
+ * (ts/test/exactjson.test.ts here) pin the returned object.
+ */
+const Decimal_1 = require("./val/Decimal");
+const err_1 = require("./err");
+const keyorder_1 = require("./keyorder");
+// JS leaves U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR)
+// literal in a JSON string; Go's encoder escapes them. Byte parity wins.
+const LSPS_RE = new RegExp('[\u2028\u2029]', 'g');
+// JSON.stringify's `space` argument, normalised the way the spec does:
+// a number is clamped to 0..10 spaces, a string is truncated to 10
+// characters, anything else means "compact".
+function indentUnit(indent) {
+    if ('number' === typeof indent) {
+        const n = Math.min(10, Math.floor(indent));
+        return 0 < n ? ' '.repeat(n) : '';
+    }
+    if ('string' === typeof indent) {
+        return indent.slice(0, 10);
+    }
+    return '';
+}
+function quote(s) {
+    const out = JSON.stringify(s);
+    // A raw separator can only appear as itself in the output (never
+    // inside an escape), so a straight replace is safe.
+    return out.replace(LSPS_RE, (c) => '\u2028' === c ? '\\u2028' : '\\u2029');
+}
+// True for a value JSON.stringify omits from an object and writes as
+// `null` inside an array. generate() never produces one, but a consumer
+// splicing its own data into the result might.
+function skipped(v) {
+    return undefined === v || 'function' === typeof v || 'symbol' === typeof v;
+}
+// `seen` tracks the containers on the CURRENT path only (added on entry,
+// removed on exit), so a shared subtree -- which unification can easily
+// produce -- serialises fine and only a true cycle is refused, exactly
+// as JSON.stringify does it.
+function emit(v, unit, pad, seen) {
+    if (null === v) {
+        return 'null';
+    }
+    const t = typeof v;
+    if ('string' === t) {
+        return quote(v);
+    }
+    if ('number' === t) {
+        // JSON has no NaN, no Infinity and no negative zero: JSON.stringify
+        // writes `null` for the first two and `0` for the last, and gen()
+        // has already normalised -0 away (R2).
+        return JSON.stringify(v);
+    }
+    if ('bigint' === t) {
+        // THE POINT OF THIS MODULE: exact digits, as a raw JSON number.
+        return v.toString();
+    }
+    if ('boolean' === t) {
+        return v ? 'true' : 'false';
+    }
+    if (skipped(v)) {
+        return 'null';
+    }
+    // Before any other object handling: a Decimal is a value, not a
+    // structure, and its plain digit form is the JSON number.
+    if (v instanceof Decimal_1.Decimal) {
+        return v.toString();
+    }
+    if ('object' === t && 'function' === typeof v.toJSON) {
+        return emit(v.toJSON(), unit, pad, seen);
+    }
+    if (seen.has(v)) {
+        throw new err_1.AontuError('aontu: cannot convert circular structure to JSON');
+    }
+    seen.add(v);
+    const inner = pad + unit;
+    const nl = '' === unit ? '' : '\n';
+    let out;
+    if (Array.isArray(v)) {
+        if (0 === v.length) {
+            out = '[]';
+        }
+        else {
+            const parts = v.map((e) => inner + emit(skipped(e) ? null : e, unit, inner, seen));
+            out = '[' + nl + parts.join(',' + nl) + nl + pad + ']';
+        }
+    }
+    else {
+        const colon = '' === unit ? ':' : ': ';
+        const parts = [];
+        // OWN enumerable keys, SORTED. A `for ... in` here would additionally
+        // walk the prototype chain.
+        //
+        // WHY THE SORT IS HERE AND NOT IN gen(). BagVal.gen already sorts map
+        // entries lexicographically -- and then writes them into a plain JS
+        // object, where ECMAScript throws that sort away. OrdinaryOwnPropertyKeys
+        // lists canonical ARRAY-INDEX keys first, in ascending NUMERIC order,
+        // and only then the remaining string keys in insertion order. So
+        // `{9:1,10:2}` came back out as 9 before 10, and `{"!":1,9:2}` put the
+        // digit key ahead of the punctuation one.
+        //
+        // This is not a V8 quirk and not a JSON.stringify quirk; it is the
+        // object's own key order, and it CANNOT be fixed upstream, because no
+        // JavaScript object can hold "10" before "9". The emitter is the last
+        // point that still has the freedom to choose, so it chooses here.
+        //
+        // The giveaway that it was never a design rule: only indices up to
+        // 2^32-2 are hoisted, so `{4294967295:1,4294967296:2,5:3}` emitted as
+        // 5, 4294967295, 4294967296 -- and TypeScript's own CANON, which builds
+        // text from a sorted list rather than from an object, was lexicographic
+        // all along. The port contradicted itself.
+        //
+        // Lexicographic by UTF-16 code unit, which is what `<` on JS strings
+        // does and what MapVal.canon/BagVal.gen already sort by. Go sorts map
+        // keys by UTF-8 byte, and the two orders agree on every key that stays
+        // inside the BMP; astral-plane keys are a separate, tracked divergence.
+        // CODE POINT order (cmpCodePoint), which is what Go's UTF-8 byte sort
+        // produces. A bare .sort() is UTF-16 code-unit order, which puts an
+        // astral key ahead of everything in U+E000-U+FFFF.
+        for (const k of Object.keys(v).sort(keyorder_1.cmpCodePoint)) {
+            const cv = v[k];
+            if (skipped(cv)) {
+                continue;
+            }
+            parts.push(inner + quote(k) + colon + emit(cv, unit, inner, seen));
+        }
+        out = 0 === parts.length ? '{}' :
+            '{' + nl + parts.join(',' + nl) + nl + pad + '}';
+    }
+    seen.delete(v);
+    return out;
+}
+/**
+ * Serialise a value produced by `Aontu.generate()` as JSON text,
+ * preserving EXACT numbers.
+ *
+ * Use this instead of `JSON.stringify` on generated output. A document
+ * that uses the `0d` exact leaves generates native `bigint` and
+ * `Decimal` values; `JSON.stringify` throws on the first and mangles the
+ * second, while this emitter writes both as raw JSON numbers with their
+ * exact digits -- which is what the D9 generate contract promises, and
+ * what the Go port's marshallers produce for the same document.
+ *
+ * ```ts
+ * import { Aontu, exactJSON } from 'aontu'
+ *
+ * const out = new Aontu().generate('x:0d9007199254740993')
+ * typeof out.x           // 'bigint'
+ * exactJSON(out)         // '{"x":9007199254740993}'
+ * exactJSON(out, 2)      // '{\n  "x": 9007199254740993\n}'
+ * JSON.stringify(out)    // TypeError: Do not know how to serialize a BigInt
+ * ```
+ *
+ * @param value   The value to serialise -- normally `generate()` output:
+ *                `null`, booleans, numbers, strings, `bigint`,
+ *                `Decimal`, arrays and plain objects. An object with a
+ *                `toJSON` method is asked for its replacement first
+ *                (`Decimal` is handled as a number before that check).
+ * @param indent  Optional indentation, with `JSON.stringify`'s `space`
+ *                semantics: a number of spaces (clamped to 0..10) or a
+ *                literal string. Omitted or `0` gives COMPACT output
+ *                (no spaces, no newlines) -- the form the shared spec
+ *                suite's `gens` mode compares byte for byte.
+ * @returns       The JSON text. Unlike `JSON.stringify` this always
+ *                returns a string: a top-level `undefined` is `null`.
+ * @throws        {AontuError} if the value contains a reference cycle.
+ */
+function exactJSON(value, indent) {
+    return emit(value, indentUnit(indent), '', new Set());
+} /* node:coverage ignore next 6 */
+//# sourceMappingURL=exactjson.js.map

package/dist/exactjson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exactjson.js","sourceRoot":"","sources":["../src/exactjson.ts"],"names":[],"mappings":"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"}

package/dist/hints.d.ts

@@ -5,4 +5,6 @@
  * Each value is a human-readable explanation of what the error means.
  */
 declare const hints: Record<string, string>;
-export { hints, };
+declare const codeClasses: Record<string, string>;
+declare function codeClass(code: string): string;
+export { hints, codeClasses, codeClass, };

package/dist/hints.js

@@ -1,7 +1,8 @@
 "use strict";
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hints = void 0;
+exports.codeClasses = exports.hints = void 0;
+exports.codeClass = codeClass;
 /**
  * Error code hints for Aontu unification errors.
  *
@@ -15,12 +16,12 @@ const hints = {
         '  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).',
+        '  1 & 1.0 -> nil  # Does not unify (kinds: Integer & Float).',
     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).',
+        '  1 & 1.0 -> nil  # Does not unify (kinds: Integer & Float).',
     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' +
@@ -37,6 +38,22 @@ const hints = {
     unknown_function: 'This function name is not recognized.',
     literal_nil: 'A literal nil cannot unify with any other value.',
     unify_cycle: 'Circular reference detected during unification.',
+    constraint: 'This value does not satisfy the constraint. A constraint is the\n' +
+        'meet of bound atoms (min, max, above, below) and exclusions (neq)\n' +
+        'over one domain; the expected form shown is the normalised\n' +
+        'residual the value must satisfy.' +
+        '\n \nExamples:\n' +
+        '  min(0) & 3                    -> 3    # Admitted (3 >= 0);\n' +
+        '  min(0) & 0d5                  -> 0d5  # Bounds are leaf-agnostic;\n' +
+        '  max(65535) & 99999            -> nil  # Above the bound;\n' +
+        '  min(5) & max(3)               -> nil  # Empty at composition time;\n' +
+        '  integer & above(1) & below(2) -> nil  # No integer in the gap;\n' +
+        '  neq(1) & 1.0                  -> 1.0  # neq excludes leaf AND value.',
+    budget_passes: 'The evaluation budget of {limit} fixpoint passes was spent before\n' +
+        'the model converged; still refining: {paths}.\n' +
+        'This is the evaluator giving up, not a contradiction in the model:\n' +
+        'raising the budget helps only a model that is still converging --\n' +
+        'a genuine cycle never converges at any budget.',
     conjunct: 'This conjunction (& operator) could not be completed as some terms\n' +
         'could not be resolved.',
     no_path: 'The path reference could not be found.' +
@@ -51,14 +68,71 @@ const hints = {
     'unite': 'Failed to unite two values. The values are incompatible and cannot be unified.',
     '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.',
+    decimal_budget: 'This exact decimal exceeds the exactness budget: at most 4096\n' +
+        'coefficient digits and an absolute scale of at most 4096. The\n' +
+        'budget applies to computed results as well as to literals.\n' +
+        'Aontu never rounds, so a value beyond the budget is refused\n' +
+        'rather than approximated.' +
+        '\n \nExamples:\n' +
+        '  0d1e1000000000    -> nil  # Scale far beyond the budget;\n' +
+        '  0d1e4000+0d1e-4000 -> nil  # An exact sum too wide to hold;\n' +
+        '  0d1e-1            -> 0d0.1  # Well within it.',
+    lossy_integer_literal: 'This integer literal, {src}, is not exactly representable in\n' +
+        'binary64, so storing it would silently round it to a DIFFERENT\n' +
+        'number. Aontu refuses rather than corrupts: write it as a `0d`\n' +
+        'literal to get the exact integer.\n' +
+        'The rule is exactness, not magnitude -- a literal far outside the\n' +
+        'int64 window is still a value when it lands exactly on a binary64.' +
+        '\n \nExamples:\n' +
+        '  9007199254740992   -> 9007199254740992    # 2^53, exact;\n' +
+        '  9007199254740993   -> nil                 # 2^53+1 is not;\n' +
+        '  0d9007199254740993 -> 0d9007199254740993  # ... the exact escape;\n' +
+        '  0x7fffffffffffffff -> nil    # 2^63-1 rounds up to 2^63;\n' +
+        '  100000000000000000000 -> 1e20 # 10^20 is huge and exact.',
+    exact_float_mix: 'Aontu cannot mix an exact number with a binary float.\n' +
+        'Here the operands are {left} and {right}, in that order.\n' +
+        'A big type never silently becomes a binary float, in either\n' +
+        'operand order -- binary64 cannot hold every exact value, so the\n' +
+        'promotion would throw away the exactness the `0d` leaves exist to\n' +
+        'guarantee. Write both operands in the same family (`0d1.0` for the\n' +
+        'float, or a plain integer for the big).' +
+        '\n \nExamples:\n' +
+        '  0d2 + 0d0.5 -> 0d2.5  # Exact with exact (widest leaf wins);\n' +
+        '  1 + 0d0.5   -> 0d1.5  # integer is on the exact ladder;\n' +
+        '  1 + 2.0     -> 3.0    # ... and float still mixes with integer;\n' +
+        '  1.0 + 0d2   -> nil    # float with biginteger;\n' +
+        '  0d0.5 + 1.0 -> nil    # ... and the same the other way round.',
+    inexact_integer_sum: 'The `integer` leaf holds a value only when it is integral, within\n' +
+        'the int64 range, and exactly representable in binary64. This sum\n' +
+        'is not: {sum}.\n' +
+        'Aontu adds integers exactly and refuses to store a rounded answer\n' +
+        '-- write `0d<digits>` for an exact integer beyond that window.' +
+        '\n \nExamples:\n' +
+        '  4503599627370496 + 4503599627370496 -> 9007199254740992  # Exact;\n' +
+        '  4503599627370496 + 4503599627370497 -> nil    # 2^53+1 is not;\n' +
+        '  0d4503599627370496 + 0d4503599627370497 -> 0d9007199254740993.',
+    'scalar-type': 'Scalar kinds only unify when one contains the other. `number` is\n' +
+        'the supertype of the numeric leaves (integer, float, biginteger,\n' +
+        'bigdecimal), so meeting it with a leaf gives that leaf; two distinct\n' +
+        'leaves describe disjoint sets of values and so have no common lower\n' +
+        'bound.' +
+        '\n \nExamples:\n' +
+        '  number & integer -> integer  # Does unify (integer is a number);\n' +
+        '  number & number  -> number   # Does unify (same kind);\n' +
+        '  float & integer  -> nil      # Does not unify (disjoint leaves).',
+    'no_scalar_unify': 'Cannot unify scalar values. The scalar values have incompatible types.' +
+        '\n \nExamples:\n' +
+        '  number & 1    -> 1    # Does unify (1 is a number);\n' +
+        '  integer & 1   -> 1    # Does unify (1 is an integer);\n' +
+        '  float & 1     -> nil  # Does not unify (1 is an integer, not a float);\n' +
+        '  integer & 1.5 -> nil  # Does not unify (1.5 is a float, not an integer).',
     '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.',
+    'key_level': 'The argument to key() is a LEVEL: how many steps up the path to look, where 0 is the key of the value itself and the default 1 is its parent. It must therefore be an integer -- `key(2)`, or `key(0d2)` for the exact leaf. A float, a decimal, a string, a boolean, a map or a list is not a level. A level beyond the top of the path is not an error; it yields the empty string.',
     '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.',
@@ -90,4 +164,112 @@ const hints = {
     'op[': 'Operator value error: ',
 };
 exports.hints = hints;
+// codeClasses assigns every error code a CLASS: conflict | incomplete |
+// reference | parse | budget | internal. The contract lives in
+// test/spec/errcodes.tsv (mode `errcode`): the spec suite executes one
+// row per code against this table and asserts SET EQUALITY between the
+// file and these keys, in both implementations (go/hints.go mirrors
+// this map exactly). Codes are append-only and never renamed; a class
+// change is a breaking change. Class rulings (why decimal_budget and
+// lossy_integer_literal are conflict, not budget; why unknown_function
+// is reference) are documented in the tsv header.
+const codeClasses = {
+    // parse -- the source text is malformed or unusable
+    parse: 'parse',
+    syntax: 'parse',
+    parse_unknown: 'parse',
+    parse_bad_src: 'parse',
+    unify_no_src: 'parse',
+    incomplete_expression: 'parse',
+    not_number: 'parse',
+    negative: 'parse',
+    decimal_syntax: 'parse',
+    // conflict -- no common lower bound, or a value refused by a rule
+    // (constraint covers the whole algebra family: membership failure,
+    // empty meets at composition time, and domain/kind mixing.)
+    constraint: 'conflict',
+    scalar_value: 'conflict',
+    scalar_kind: 'conflict',
+    no_scalar_unify: 'conflict',
+    'scalar-type': 'conflict',
+    'not-scalar-type': 'conflict',
+    map: 'conflict',
+    list: 'conflict',
+    closed: 'conflict',
+    literal_nil: 'conflict',
+    nil_gen: 'conflict',
+    unite: 'conflict',
+    '|:empty': 'conflict',
+    '|:empty-dist': 'conflict',
+    exact_float_mix: 'conflict',
+    inexact_integer_sum: 'conflict',
+    decimal_budget: 'conflict',
+    lossy_integer_literal: 'conflict',
+    arg: 'conflict',
+    'invalid-arg': 'conflict',
+    no_first_arg: 'conflict',
+    key_level: 'conflict',
+    func: 'conflict',
+    'func:': 'conflict',
+    op: 'conflict',
+    'op:': 'conflict',
+    'op[': 'conflict',
+    make: 'conflict',
+    resolve: 'conflict',
+    operate: 'conflict',
+    close: 'conflict',
+    // incomplete -- residue: the truth requires more than was supplied
+    no_gen: 'incomplete',
+    conjunct: 'incomplete',
+    mapval_no_gen: 'incomplete',
+    mapval_required: 'incomplete',
+    mapval_spread_required: 'incomplete',
+    listval_no_gen: 'incomplete',
+    listval_required: 'incomplete',
+    listval_spread_required: 'incomplete',
+    required_listelem: 'incomplete',
+    // reference -- a name or path that does not resolve
+    no_path: 'reference',
+    // A PROVEN structural cycle is a defect of the model, not a spent
+    // evaluation bound: raising a budget never fixes it (G5's ruling --
+    // class budget means "retry with more may help", path_cycle means
+    // "fix the model").
+    path_cycle: 'reference',
+    ref: 'reference',
+    'ref[': 'reference',
+    var: 'reference',
+    'var[': 'reference',
+    unknown_var: 'reference',
+    invalid_var_kind: 'reference',
+    unknown_function: 'reference',
+    multisource_not_found: 'reference',
+    // budget -- an evaluation bound was exceeded
+    unify_cycle: 'budget',
+    max_depth: 'budget',
+    budget_passes: 'budget',
+    // internal -- the engine reached a state it should not reach
+    internal: 'internal',
+    unify_no_res: 'internal',
+    unknown_op: 'internal',
+};
+exports.codeClasses = codeClasses;
+// Dynamic-prefix families: the engine appends a name or value to these
+// (e.g. `func:upper`, `op:+`, `var[string]`, `ref[$.x]`, `op[+]`), so
+// class lookup falls back to the registered prefix.
+const CODE_PREFIXES = ['func:', 'op:', 'op[', 'var[', 'ref['];
+// The class of an error code: an exact registry entry, else the
+// registered dynamic prefix it extends, else `internal` -- an
+// unregistered code is an engine defect, not a user error.
+function codeClass(code) {
+    const cls = codeClasses[code];
+    if (null != cls) {
+        return cls;
+    }
+    for (const prefix of CODE_PREFIXES) {
+        if (code.startsWith(prefix)) {
+            return codeClasses[prefix];
+        }
+    }
+    return 'internal';
+} /* node:coverage ignore next 8 */
 //# sourceMappingURL=hints.js.map

package/dist/hints.js.map

@@ -1 +1 @@
-{"version":3,"file":"hints.js","sourceRoot":"","sources":["../src/hints.ts"],"names":[],"mappings":";AAAA,oDAAoD;;;AAEpD;;;;;GAKG;AAEH,MAAM,KAAK,GAA2B;IAEpC,YAAY,EACV,qEAAqE;QACrE,gBAAgB;QAChB,kBAAkB;QAClB,oDAAoD;QACpD,mDAAmD;QACnD,0DAA0D;QAC1D,+DAA+D;IAEjE,WAAW,EACT,wDAAwD;QACxD,kBAAkB;QAClB,oDAAoD;QACpD,iEAAiE;QACjE,+DAA+D;IAEjE,OAAO,EACL,kEAAkE;QAClE,+CAA+C;IAEjD,MAAM,EACJ,qEAAqE;QACrE,oCAAoC;IAGtC,6DAA6D;IAC7D,eAAe,EAAE,6BAA6B;IAE9C,aAAa,EACX,qEAAqE;QACrE,oCAAoC;IAEtC,sBAAsB,EACpB,0DAA0D;IAE5D,gBAAgB,EAAE,gCAAgC;IAElD,cAAc,EACZ,4EAA4E;QAC5E,oCAAoC;IAEtC,uBAAuB,EACrB,0DAA0D;IAE5D,gBAAgB,EACd,uCAAuC;IAEzC,WAAW,EACT,kDAAkD;IAEpD,WAAW,EAAE,iDAAiD;IAE9D,QAAQ,EACN,sEAAsE;QACtE,wBAAwB;IAE1B,OAAO,EAAE,wCAAwC;QAC/C,kBAAkB;QAClB,uFAAuF;QACvF,kGAAkG;IAEpG,iBAAiB;IACjB,eAAe,EAAE,6EAA6E;IAE9F,qBAAqB;IACrB,cAAc,EAAE,yEAAyE;IACzF,cAAc,EAAE,kEAAkE;IAClF,OAAO,EAAE,gFAAgF;IAEzF,UAAU,EAAE,mGAAmG;IAE/G,uBAAuB;IAEvB,aAAa,EAAE,0DAA0D;IACzE,iBAAiB,EAAE,wEAAwE;IAC3F,iBAAiB,EAAE,mDAAmD;IACtE,KAAK,EAAE,+DAA+D;IACtE,MAAM,EAAE,gEAAgE;IAExE,kBAAkB;IAClB,KAAK,EAAE,mFAAmF;IAC1F,aAAa,EAAE,qFAAqF;IACpG,cAAc,EAAE,uFAAuF;IAEvG,kBAAkB;IAClB,aAAa,EAAE,gEAAgE;IAC/E,kBAAkB,EAAE,4EAA4E;IAEhG,4BAA4B;IAC5B,UAAU,EAAE,8DAA8D;IAC1E,KAAK,EAAE,0EAA0E;IAEjF,2BAA2B;IAC3B,QAAQ,EAAE,kGAAkG;IAC5G,mBAAmB,EAAE,6EAA6E;IAElG,2CAA2C;IAC3C,SAAS,EAAE,+DAA+D;IAC1E,cAAc,EAAE,kFAAkF;IAElG,WAAW,EAAE,8CAA8C;IAE3D,qCAAqC;IACrC,MAAM,EAAE,wEAAwE;IAChF,MAAM,EAAE,iFAAiF;IACzF,SAAS,EAAE,wFAAwF;IACnG,SAAS,EAAE,6EAA6E;IAExF,qCAAqC;IACrC,IAAI,EAAE,wEAAwE;IAE9E,kBAAkB;IAClB,OAAO,EAAE,+DAA+D;IAExE,6CAA6C;IAC7C,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,uBAAuB;IAC/B,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,wBAAwB;CAChC,CAAA;QAIC,KAAK"}
+{"version":3,"file":"hints.js","sourceRoot":"","sources":["../src/hints.ts"],"names":[],"mappings":"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"}

package/dist/keyorder.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+declare function cmpCodePoint(a: string, b: string): number;
+export { cmpCodePoint, };

package/dist/keyorder.js

@@ -0,0 +1,65 @@
+"use strict";
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmpCodePoint = cmpCodePoint;
+/*
+ * 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, b) {
+    // 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]();
+    for (;;) {
+        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;
+        }
+        if (y.done) {
+            return 1;
+        }
+        const xc = x.value.codePointAt(0);
+        const yc = y.value.codePointAt(0);
+        if (xc !== yc) {
+            return xc < yc ? -1 : 1;
+        }
+    }
+} /* node:coverage ignore next 6 */
+//# sourceMappingURL=keyorder.js.map

package/dist/keyorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyorder.js","sourceRoot":"","sources":["../src/keyorder.ts"],"names":[],"mappings":";AAAA,oDAAoD;;QAuElD,YAAY;AArEd;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS;IACxC,sEAAsE;IACtE,wEAAwE;IACxE,oEAAoE;IACpE,mDAAmD;IACnD,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAA;IAC/B,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAA;IAE/B,SAAU,CAAC;QACT,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAA;QACnB,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAA;QAEnB,oEAAoE;QACpE,2DAA2D;QAC3D,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACX,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACxB,CAAC;QACD,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACX,OAAO,CAAC,CAAA;QACV,CAAC;QAED,MAAM,EAAE,GAAI,CAAC,CAAC,KAAgB,CAAC,WAAW,CAAC,CAAC,CAAW,CAAA;QACvD,MAAM,EAAE,GAAI,CAAC,CAAC,KAAgB,CAAC,WAAW,CAAC,CAAC,CAAW,CAAA;QAEvD,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACzB,CAAC;IACH,CAAC;AACH,CAAC,CAAC,iCAAiC"}