@tabnas/json 0.5.12 → 0.5.14

package/dist/json.d.ts

@@ -1,5 +1,5 @@
 import { Tabnas, TabnasError, type Plugin } from '@tabnas/parser';
-export declare const VERSION = "0.5.12";
+export declare const VERSION = "0.5.14";
 export interface JsonGrammarOptions {
     chainOff?: boolean;
 }

package/dist/json.js

@@ -29,7 +29,7 @@ Object.defineProperty(exports, "JsonError", { enumerable: true, get: function ()
 // VERSION is this package's version. It MUST equal package.json "version":
 // the release orchestrator rewrites both, and test/version.test.js fails the
 // build if they drift. Mirrors `const VERSION` in go/json.go.
-exports.VERSION = '0.5.12';
+exports.VERSION = '0.5.14';
 // JSON-only lexer/parser options. Restrictive enough to mirror
 // JSON.parse: double-quoted strings only, plain decimal numbers, quoted
 // keys only, no comments, no trailing-comma map extension, no empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabnas/json",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "main": "dist/json.js",
   "type": "commonjs",
   "types": "dist/json.d.ts",
@@ -38,7 +38,9 @@
   },
   "files": [
     "dist",
+    "src",
     "bin",
+    "README.md",
     "LICENSE"
   ],
   "bin": {

package/src/json-cli.ts

@@ -0,0 +1,51 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+/* json-cli.ts
+ *
+ * A tiny command-line front end: read JSON from the arguments or from
+ * stdin, parse it, and print the canonical re-serialized form. Exit code
+ * 1 (with the error on stderr) when the input is not valid JSON.
+ *
+ * The logic is split into `run` (pure: source in, exit code out, writes
+ * via injected sinks) and `main` (process wiring), so `run` and `main`
+ * are both testable in-process. `bin/json` calls `main`.
+ */
+
+import { parse, TabnasError } from './json'
+
+// Parse `src`, writing the pretty-printed value to `out` on success or
+// the error message to `errOut` on failure. Returns the process exit code.
+export function run(
+  src: string,
+  out: (s: string) => void,
+  errOut: (s: string) => void,
+): number {
+  try {
+    out(JSON.stringify(parse(src), null, 2) + '\n')
+    return 0
+  } catch (err) {
+    if (err instanceof TabnasError) {
+      errOut(err.message + '\n')
+      return 1
+    }
+    throw err
+  }
+}
+
+// Wire `run` to a process-like environment. With arguments, parse them;
+// otherwise read all of stdin. Calls `exit` with the resulting code.
+export function main(
+  argv: string[],
+  stdin: NodeJS.ReadableStream,
+  out: (s: string) => void,
+  errOut: (s: string) => void,
+  exit: (code: number) => void,
+): void {
+  if (argv.length > 0) {
+    exit(run(argv.join(' '), out, errOut))
+    return
+  }
+  const chunks: Buffer[] = []
+  stdin.on('data', (c: Buffer) => chunks.push(Buffer.from(c)))
+  stdin.on('end', () => exit(run(Buffer.concat(chunks).toString('utf8'), out, errOut)))
+}

package/src/json.ts

@@ -0,0 +1,264 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+/*  json.ts
+ *
+ *  A standard JSON grammar plugin for the `tabnas` parsing engine.
+ *
+ *  The engine ships no grammar of its own; this package supplies the
+ *  strict, standard-JSON one. The rule set (val / map / list / pair /
+ *  elem) is the "Plain JSON" grammar from jsonic's `grammar.ts` — the
+ *  pure-JSON core jsonic defines before extending it for the relaxed
+ *  jsonic format. Here that core is installed on its own, with the lexer
+ *  restricted to strict JSON, and none of jsonic's extended grammar
+ *  (comments, unquoted keys, implicit objects/arrays, trailing commas,
+ *  single/backtick strings, path diving).
+ *
+ *  This plugin is intended to be the foundation other tabnas grammar
+ *  plugins build on: `use` it first, then layer additional rules on the
+ *  shared val / map / list / pair / elem rules.
+ */
+
+import { Tabnas, TabnasError, type Plugin } from '@tabnas/parser'
+
+// VERSION is this package's version. It MUST equal package.json "version":
+// the release orchestrator rewrites both, and test/version.test.js fails the
+// build if they drift. Mirrors `const VERSION` in go/json.go.
+export const VERSION = '0.5.14'
+
+// JSON-only lexer/parser options. Restrictive enough to mirror
+// JSON.parse: double-quoted strings only, plain decimal numbers, quoted
+// keys only, no comments, no trailing-comma map extension, no empty
+// input, and the rule set restricted to the `json`-tagged alternates.
+const JSON_OPTIONS = {
+  text: { lex: false },
+  number: {
+    hex: false,
+    oct: false,
+    bin: false,
+    sep: null,
+    // Reject any token the (lenient) number matcher accepts that is not a
+    // strict JSON number: leading `+`, a bare leading `.` (`.5`), a
+    // trailing `.` (`1.`), and leading zeros (`01`, `00`). The negative
+    // lookahead matches — and so excludes — anything not of the form
+    // -?(0|[1-9][0-9]*)(.[0-9]+)?([eE][+-]?[0-9]+)?.
+    exclude: /^(?!-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$)/,
+  },
+  string: {
+    chars: '"',
+    multiChars: '',
+    // Standard JSON escape handling: allowUnknown:false rejects any
+    // unrecognized escape (\q, \z); escapeStrict disables the engine's
+    // non-standard \xHH and \u{...} structural escapes (plain \uXXXX
+    // stays); and dropping v / ' / ` from the escape map removes the
+    // remaining non-standard built-ins. Result: exactly the JSON.parse
+    // escape set, identical to the Go engine.
+    allowUnknown: false,
+    escapeStrict: true,
+    escape: { v: '', "'": '', '`': '' },
+  },
+  comment: { lex: false },
+  map: { extend: false },
+  lex: { empty: false },
+  rule: { finish: false, include: 'json' },
+  result: { fail: [undefined, NaN] },
+  tokenSet: { KEY: ['#ST', null, null, null] },
+}
+
+// Options for `registerJsonGrammar`. The zero state -- no argument at
+// all -- installs the layerable grammar, which is the safe default.
+export interface JsonGrammarOptions {
+  // Declare that no rule in the ASSEMBLED grammar resolves `$prev`, so
+  // `@push$` need not re-publish the grown list back along the
+  // `r: 'elem'` replacement chain. The JSON core never reads a replaced
+  // rule, but a plugin layering its own alternates onto `elem` or `list`
+  // might, and only that plugin knows. So the core cannot make the claim
+  // on its behalf: it is off here and the complete `json` plugin -- the
+  // parser nobody has extended -- is what turns it on.
+  //
+  // A no-op in this runtime and in Rust, which hand out one array object
+  // that every view of the list already shares. It matters in Go, where a
+  // list is a slice VALUE and the walk it skips is O(elements^2).
+  chainOff?: boolean
+}
+
+// Install the pure JSON rule set (val / map / list / pair / elem) on the
+// given engine instance. Exposed separately from the options so other
+// grammar plugins can layer their extensions on top without re-declaring
+// the JSON core. This is jsonic's "Plain JSON" grammar.
+export function registerJsonGrammar(
+  tn: Tabnas,
+  opts?: JsonGrammarOptions,
+): void {
+  // Spread onto the two `elem` close alts. Nothing is emitted unless
+  // asked for, and an absent `k` is the engine default: the walk runs.
+  // Called per alt so each gets its OWN object, as the two literals it
+  // replaces did: alt config is the engine's to read, and two alts
+  // sharing one object would make that an assumption rather than a fact.
+  const pushChain = () =>
+    opts?.chainOff ? { k: { push$: { chain: false } } } : {}
+
+  tn.grammar({
+    // The schema version of the native-value builtins this grammar binds
+    // to (object/array/reset/key/setval/push/value).
+    v: 2,
+
+    // The value tree is built ENTIRELY by the engine's native-value
+    // `$`-builtins — referenced by name on the alts below; the engine
+    // merges them in at load. There are NO grammar-local closures: the
+    // builders are info-aware, so when info.map/list/text is enabled they
+    // attach the introspection marker themselves (the json plugin used to
+    // hand-write that as @jsonMapMark/@jsonListMark/@jsonText/@jsonSetval).
+    // Strict JSON containers are always explicit, so @object$/@array$ take
+    // the default implicit:false (no `k` config needed).
+    //
+    // The builtin actions used below, one line each:
+    //   @reset$  — clear the parent-seeded node (so a value doesn't inherit
+    //              the parent container).
+    //   @object$ — allocate an empty object into the node (a MapRef under
+    //              info.map).
+    //   @array$  — allocate an empty array into the node (a ListRef under
+    //              info.list).
+    //   @key$    — capture the matched key token into a scratch slot for the
+    //              pending @setval$.
+    //   @setval$ — assign the just-built child value into the object under
+    //              the captured key.
+    //   @push$   — append the just-built child value to the array.
+    //   @value$  — resolve the rule's value: a built child wins, else the
+    //              scalar token (boxed with quote info under info.text).
+    rule: {
+      val: {
+        // Opening token alternates. @reset$ clears the parent-seeded node
+        // so a scalar doesn't inherit the parent container.
+        open: [
+          // A map: `{ ...`
+          { s: '#OB', p: 'map', b: 1, a: '@reset$', g: 'map,json' },
+
+          // A list: `[ ...`
+          { s: '#OS', p: 'list', b: 1, a: '@reset$', g: 'list,json' },
+
+          // A plain value: `"x"` `1` `true` ....
+          { s: '#VAL', a: '@reset$', g: 'val,json' },
+        ],
+
+        // Closing alternates. @value$ coalesces (child wins, else the
+        // scalar token) and, under info.text, boxes a string with its quote.
+        close: [
+          // End of input.
+          { s: '#ZZ', a: '@value$', g: 'end,json' },
+
+          // There's more JSON.
+          { b: 1, a: '@value$', g: 'more,json' },
+        ],
+      },
+
+      map: {
+        open: [
+          // An empty map: {}.
+          { s: '#OB #CB', b: 1, n: { pk: 0 }, a: '@object$', g: 'map,json' },
+
+          // Start matching map key-value pairs.
+          // Reset counter n.pk as new map (for extensions).
+          { s: '#OB', p: 'pair', n: { pk: 0 }, a: '@object$', g: 'map,json,pair' },
+        ],
+        close: [
+          // End of map.
+          { s: '#CB', g: 'end,json' },
+        ],
+      },
+
+      list: {
+        open: [
+          // An empty list: [].
+          { s: '#OS #CS', b: 1, a: '@array$', g: 'list,json' },
+
+          // Start matching list elements.
+          { s: '#OS', p: 'elem', a: '@array$', g: 'list,elem,json' },
+        ],
+        close: [
+          // End of list.
+          { s: '#CS', g: 'end,json' },
+        ],
+      },
+
+      // sets key:val on node
+      pair: {
+        open: [
+          // Match key-colon start of pair. @key$ captures the key.
+          {
+            s: '#KEY #CL',
+            p: 'val',
+            u: { pair: true },
+            a: '@key$',
+            g: 'map,pair,key,json',
+          },
+        ],
+        close: [
+          // Comma means a new pair at same pair-key level. @setval$
+          // assigns the pair; on every close alt (fan-out).
+          { s: '#CA', r: 'pair', a: '@setval$', g: 'map,pair,comma,json' },
+
+          // End of map.
+          { s: '#CB', b: 1, a: '@setval$', g: 'map,pair,close,json' },
+        ],
+      },
+
+      // push onto node
+      elem: {
+        open: [
+          // List elements are values.
+          { p: 'val', g: 'list,elem,val,json' },
+        ],
+        close: [
+          // Next element. @push$ appends the element. `r: 'elem'`
+          // REPLACES this rule, so the rule it displaces keeps its own
+          // view of the list -- which is why `chainOff` is a claim only
+          // the assembled grammar can make. See JsonGrammarOptions.
+          { s: '#CA', r: 'elem', a: '@push$',
+            ...pushChain(), g: 'list,elem,comma,json' },
+
+          // End of list.
+          { s: '#CS', b: 1, a: '@push$',
+            ...pushChain(), g: 'list,elem,close,json' },
+        ],
+      },
+    },
+  })
+}
+
+// The standard plugin form: apply the strict JSON options, then register
+// the JSON grammar. `use` this on a bare engine, or pass it to `make`.
+export const json: Plugin = function json(tn: Tabnas, _options?: any) {
+  tn.options(JSON_OPTIONS)
+  // The complete parser: these rules are the whole grammar, and none of
+  // them reads a replaced rule. That is what makes `chainOff` true here
+  // and false in the rules-only installer above.
+  registerJsonGrammar(tn, { chainOff: true })
+}
+
+// Create a standard-JSON parser instance: a tabnas engine with the json
+// plugin installed. Extra options (e.g. info.map/list/text) are applied
+// after the grammar exists, mirroring the Go `Make`.
+export function make(opts?: Record<string, any>): Tabnas {
+  const tn = new Tabnas({ plugins: [json] })
+  if (opts) {
+    tn.options(opts)
+  }
+  return tn
+}
+
+// A lazily-created default instance reused by `parse`, so repeated calls
+// don't rebuild the engine and grammar each time. Parsing creates a fresh
+// context per call, so reuse is safe.
+let defaultParser: Tabnas | undefined
+
+// Parse a JSON source string with a default standard-JSON parser and
+// return the resulting value. Throws a TabnasError on invalid input.
+export function parse(src: string): any {
+  return (defaultParser ??= make()).parse(src)
+}
+
+export { Tabnas, TabnasError }
+export { TabnasError as JsonError }
+export { translate } from './translate'
+export type { TranslationPart, TranslationParts } from './translate'
+export default parse

package/src/translate.ts

@@ -0,0 +1,76 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// Generated by ../embed-translate.js. Edit tabnas.plugin.json or alchemy/*,
+// then run npm run embed.
+
+type TranslationPart = Readonly<{
+  entry: string
+  source?: string
+}>
+
+type TranslationParts = Readonly<{
+  manifest: string
+  lift?: TranslationPart
+  render?: TranslationPart
+}>
+
+const TRANSLATION: TranslationParts = Object.freeze({
+  manifest: `{
+  "$schema": "https://tabnas.dev/schema/plugin.schema.json",
+  "name": "@tabnas/json",
+  "go": "github.com/tabnas/json/go",
+  "description": "A standard JSON parser (RFC 8259) for the tabnas engine.",
+  "engine": "@tabnas/parser",
+  "extensions": [
+    ".json"
+  ],
+  "mediaTypes": [
+    "application/json"
+  ],
+  "languageId": "json",
+  "pluginKind": "grammar",
+  "grammarKind": "data",
+  "lexStream": "clean",
+  "syncGroups": [
+    "end",
+    "comma",
+    "close"
+  ],
+  "specDir": "test/spec",
+  "clib": {
+    "dir": "go/clib",
+    "library": "libtabnasjson",
+    "abi": "v1",
+    "errorCodes": [
+      "usage",
+      "grammar",
+      "handle",
+      "internal"
+    ]
+  },
+  "errorCodes": [],
+  "docs": "https://tabnas.dev/docs/packages",
+  "repository": "https://github.com/tabnas/json",
+  "versionSource": "ts/package.json",
+  "translate": {
+    "reads": "tree",
+    "writes": "tree",
+    "render": "json"
+  }
+}
+`,
+  render: Object.freeze({ entry: "json" })
+})
+
+function translate (): TranslationParts | undefined {
+  return TRANSLATION
+}
+
+export {
+  translate,
+}
+
+export type {
+  TranslationPart,
+  TranslationParts,
+}

package/src/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir": "../dist",
+    "rootDir": ".",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2021",
+    "declaration": true,
+    "declarationDir": "../dist",
+    "types": ["node"]
+  }
+}