@starci/eslint-grammar-core 0.15.34 → 0.16.2

package/runtime/scripts/hfs/view.mjs

@@ -5,10 +5,8 @@
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { openHfs } from './slots.mjs';
-
 const posix = (p) => String(p).replaceAll('\\', '/');
 const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
-
 /**
  * The view rules read, over an opened resolver.
  *
@@ -17,44 +15,45 @@ const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(tex
  * @returns {object} The frozen view: profile, apps, connections, patterns, ruleParams, relative, classify, slotOf, tierOf, ownerOf, slot.
  */
 function hfsView(opened, repoRoot) {
-  const rel = (file) => {
-    const text = posix(file);
-    if (!isAbsoluteAny(text)) return text.replace(/^\.\//, '');
-    return posix(path.relative(repoRoot, file));
-  };
-  const slotCache = new Map();
-  const classify = (file) => {
-    const key = rel(file);
-    if (!slotCache.has(key)) slotCache.set(key, opened.classifyPath(key));
-    return slotCache.get(key);
-  };
-  return Object.freeze({
-    repoRoot,
-    profile: opened.repo.profile,
-    side: opened.repo.side ?? null,
-    edition: opened.repo.edition ?? 'full',
-    ...(opened.repo.grammar === undefined ? {} : { grammar: opened.repo.grammar }),
-    apps: opened.repo.apps,
-    connections: opened.repo.connections,
-    patterns: Object.freeze([...(opened.repo.patterns ?? [])]),
-    ruleParams: opened.ruleParams(),
-    /** The repository-relative, forward-slash form of a linted filename. */
-    relative: rel,
-    /** The classification of a file: `{ slot, tier, owner?, bindings? ... }` or a no-slot status. */
-    classify,
-    /** The slot id that owns a file, or null when no slot does. */
-    slotOf: (file) => classify(file).slot ?? null,
-    /** The tier of a file, or null. */
-    tierOf: (file) => opened.tierOf(rel(file)) ?? null,
-    /** The owner root of a file, or null. */
-    ownerOf: (file) => opened.ownerOf(rel(file))?.root ?? null,
-    /** What the slot that owns a file says about it: `{ slot, root, relative, allowed, entry?, forbiddenBy?, allows }`, or null when the slot names no `allows`. */
-    allows: (file) => allowsFile(opened, rel(file)),
-    /** A slot definition by id. */
-    slot: (id) => opened.slot(id),
-  });
+    const rel = (file) => {
+        const text = posix(file);
+        if (!isAbsoluteAny(text))
+            return text.replace(/^\.\//, '');
+        return posix(path.relative(repoRoot, file));
+    };
+    const slotCache = new Map();
+    const classify = (file) => {
+        const key = rel(file);
+        if (!slotCache.has(key))
+            slotCache.set(key, opened.classifyPath(key));
+        return slotCache.get(key);
+    };
+    return Object.freeze({
+        repoRoot,
+        profile: opened.repo.profile,
+        side: opened.repo.side ?? null,
+        edition: opened.repo.edition ?? 'full',
+        ...(opened.repo.grammar === undefined ? {} : { grammar: opened.repo.grammar }),
+        apps: opened.repo.apps,
+        connections: opened.repo.connections,
+        patterns: Object.freeze([...(opened.repo.patterns ?? [])]),
+        ruleParams: opened.ruleParams(),
+        /** The repository-relative, forward-slash form of a linted filename. */
+        relative: rel,
+        /** The classification of a file: `{ slot, tier, owner?, bindings? ... }` or a no-slot status. */
+        classify,
+        /** The slot id that owns a file, or null when no slot does. */
+        slotOf: (file) => classify(file).slot ?? null,
+        /** The tier of a file, or null. */
+        tierOf: (file) => opened.tierOf(rel(file)) ?? null,
+        /** The owner root of a file, or null. */
+        ownerOf: (file) => opened.ownerOf(rel(file))?.root ?? null,
+        /** What the slot that owns a file says about it: `{ slot, root, relative, allowed, entry?, forbiddenBy?, allows }`, or null when the slot names no `allows`. */
+        allows: (file) => allowsFile(opened, rel(file)),
+        /** A slot definition by id. */
+        slot: (id) => opened.slot(id),
+    });
 }
-
 /**
  * The view of the app folder on disk at `repoRoot`, against the manifest under `runtimeRoot`: a side folder (be/, fe/) finds the
  * app-root hfs.json one level up and gets that side's view, so every linted file below it is judged by its own side's slots.
@@ -63,7 +62,6 @@ function hfsView(opened, repoRoot) {
  * @returns {object} The frozen view.
  */
 export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root: runtimeRoot, repoRoot }), repoRoot);
-
 /**
  * The view of one side of an in-memory app declaration (rule tests): no file is read except the manifest.
  *

package/runtime/scripts/lib/glob.mjs

@@ -1,23 +1,32 @@
 // glob.mjs — the path-glob subset ESLint, SonarQube and the scoped-lint config share: `**` spans directories,
 // `*` and `?` stay inside one segment, `{a,b}` alternates.
 import { posixPath } from './path-key.mjs';
-
 /** Every alternative a `{a,b}` pattern spells, braces expanded left to right. */
 export function braceVariants(value) {
-  const match = /\{([^{}]+)\}/.exec(value);
-  return match ? match[1].split(',').flatMap((part) => braceVariants(`${value.slice(0, match.index)}${part}${value.slice(match.index + match[0].length)}`)) : [value];
+    const match = /\{([^{}]+)\}/.exec(value);
+    return match ? match[1].split(',').flatMap((part) => braceVariants(`${value.slice(0, match.index)}${part}${value.slice(match.index + match[0].length)}`)) : [value];
 }
-
 /** The anchored RegExp of one brace-free glob, read as a posix path (backslashes and a leading './' folded). */
 export function globExpression(value) {
-  const input = posixPath(value);
-  let source = '';
-  for (let i = 0; i < input.length; i += 1) {
-    const c = input[i];
-    if (c === '*' && input[i + 1] === '*') { i += 1; if (input[i + 1] === '/') { i += 1; source += '(?:.*/)?'; } else source += '.*'; }
-    else if (c === '*') source += '[^/]*';
-    else if (c === '?') source += '[^/]';
-    else source += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
-  }
-  return new RegExp(`^${source}$`);
+    const input = posixPath(value);
+    let source = '';
+    for (let i = 0; i < input.length; i += 1) {
+        const c = input.charAt(i);
+        if (c === '*' && input[i + 1] === '*') {
+            i += 1;
+            if (input[i + 1] === '/') {
+                i += 1;
+                source += '(?:.*/)?';
+            }
+            else
+                source += '.*';
+        }
+        else if (c === '*')
+            source += '[^/]*';
+        else if (c === '?')
+            source += '[^/]';
+        else
+            source += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+    }
+    return new RegExp(`^${source}$`);
 }

package/runtime/scripts/lib/grammar-lint.mjs

@@ -1,61 +1,57 @@
 // Grammar-family lint selection reads the family catalog; an absent selection never chooses a family.
 import fs from 'node:fs';
 import { parseYamlCached } from './yaml-cached.mjs';
-
 const CATALOG_FILE = new URL('../../knowledge/grammars/index.yaml', import.meta.url);
-
 function readCatalog() {
-  return parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
+    return parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
 }
-
 function selectedFamily(family) {
-  if (typeof family !== 'string' || !family.trim()) throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
-  const catalog = readCatalog();
-  const matches = (catalog.families ?? []).filter(entry => entry.id === family);
-  if (matches.length !== 1) throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
-  return { catalog, selected: matches[0] };
+    if (typeof family !== 'string' || !family.trim())
+        throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
+    const catalog = readCatalog();
+    const matches = (catalog.families ?? []).filter(entry => entry.id === family);
+    if (matches.length !== 1)
+        throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
+    return { catalog, selected: matches[0] };
 }
-
 /**
  * Resolve a selection to its declared family id; only a catalog family id resolves, there are no aliases.
  * @param {string} family - The id an app or caller names (sides.fe.grammar).
  * @returns {{ id: string }} The declared family id.
  */
 export function resolveGrammarFamily(family) {
-  return Object.freeze({ id: selectedFamily(family).selected.id });
+    return Object.freeze({ id: selectedFamily(family).selected.id });
 }
-
 /** The explicitly selected authored family entry; callers share the catalog lookup rather than inferring a family. */
 export function grammarFamilyFor(family) {
-  return Object.freeze(selectedFamily(family).selected);
+    return Object.freeze(selectedFamily(family).selected);
 }
-
 /** The declared family's lint contract, including an explicit null package when that family has no rules. */
 export function grammarLintFor(family) {
-  const { selected } = selectedFamily(family);
-  if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
-    throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
-  }
-  const lint = selected.lint;
-  if (lint.package === null) return Object.freeze({ family: selected.id, package: null });
-  if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
-    || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
-    || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
-    throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
-  }
-  return Object.freeze({ family: selected.id, package: lint.package, factory: lint.factory, prefix: lint.prefix });
+    const { selected } = selectedFamily(family);
+    if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
+        throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
+    }
+    const lint = selected.lint;
+    if (lint.package === null)
+        return Object.freeze({ family: selected.id, package: null });
+    if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
+        || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
+        || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
+        throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
+    }
+    return Object.freeze({ family: selected.id, package: lint.package, factory: lint.factory, prefix: lint.prefix });
 }
-
 /** The selected family's shared component/export contract, resolved through its catalog reference. */
 export function grammarContractFor(family) {
-  const { catalog, selected } = selectedFamily(family);
-  const owners = (catalog.families ?? []).filter(entry => entry.id === selected.contractRef);
-  const contract = owners.length === 1 ? owners[0].componentContract : null;
-  if (!contract || typeof contract.package !== 'string' || !contract.package
-    || typeof contract.entry !== 'string' || !contract.entry.startsWith(`${contract.package}/`)
-    || typeof contract.styleEntry !== 'string' || !contract.styleEntry.startsWith(`${contract.package}/`)
-    || !Array.isArray(contract.peers) || !contract.peers.every(peer => typeof peer === 'string' && peer.trim())) {
-    throw new Error(`Grammar family ${family} has no valid component contract in knowledge/grammars/index.yaml`);
-  }
-  return Object.freeze({ ...contract, peers: Object.freeze([...contract.peers]) });
+    const { catalog, selected } = selectedFamily(family);
+    const owners = (catalog.families ?? []).filter(entry => entry.id === selected.contractRef);
+    const contract = owners.length === 1 ? owners[0]?.componentContract : null;
+    if (!contract || typeof contract.package !== 'string' || !contract.package
+        || typeof contract.entry !== 'string' || !contract.entry.startsWith(`${contract.package}/`)
+        || typeof contract.styleEntry !== 'string' || !contract.styleEntry.startsWith(`${contract.package}/`)
+        || !Array.isArray(contract.peers) || !contract.peers.every(peer => typeof peer === 'string' && peer.trim())) {
+        throw new Error(`Grammar family ${family} has no valid component contract in knowledge/grammars/index.yaml`);
+    }
+    return Object.freeze({ ...contract, peers: Object.freeze([...contract.peers]) });
 }

package/runtime/scripts/lib/i18n.mjs

@@ -18,68 +18,65 @@ import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { DEFAULT_OWNER_LANGUAGE, loadConfig } from '../../engine/config.mjs';
-
 export const CATALOG_DIR = 'modules/i18n/messages';
 export const PLACEHOLDER = /\{([A-Za-z_]\w*)\}/g;
-
 const cache = new Map();
-
 /** The catalog files of a runtime root: repository-relative paths, sorted. */
 export function catalogFiles(root = skillRoot) {
-  const dir = path.join(root, ...CATALOG_DIR.split('/'));
-  try { return fs.readdirSync(dir).filter((name) => /\.ya?ml$/.test(name)).sort().map((name) => `${CATALOG_DIR}/${name}`); } catch { return []; }
+    const dir = path.join(root, ...CATALOG_DIR.split('/'));
+    try {
+        return fs.readdirSync(dir).filter((name) => /\.ya?ml$/.test(name)).sort().map((name) => `${CATALOG_DIR}/${name}`);
+    }
+    catch {
+        return [];
+    }
 }
-
 /** Every entry in one catalog scope: `[{ en, vi, area, scope, file }]`. */
 export function catalogEntries(root = skillRoot, { scope = 'runtime' } = {}) {
-  return catalogFiles(root).flatMap((rel) => {
-    const doc = parseYaml(fs.readFileSync(path.join(root, ...rel.split('/')), 'utf8'));
-    const documentScope = typeof doc?.scope === 'string' ? doc.scope : 'runtime';
-    if (documentScope !== scope) return [];
-    return (Array.isArray(doc?.messages) ? doc.messages : []).map((entry) => ({
-      en: entry?.en, vi: entry?.vi, area: doc?.area, scope: documentScope, file: rel,
-    }));
-  });
+    return catalogFiles(root).flatMap((rel) => {
+        const doc = parseYaml(fs.readFileSync(path.join(root, ...rel.split('/')), 'utf8'));
+        const documentScope = typeof doc?.scope === 'string' ? doc.scope : 'runtime';
+        if (documentScope !== scope)
+            return [];
+        return (Array.isArray(doc?.messages) ? doc.messages : []).map((entry) => ({
+            en: entry?.en, vi: entry?.vi, area: doc?.area, scope: documentScope, file: rel,
+        }));
+    });
 }
-
 /** One scoped catalog as a Map from the English source to the Vietnamese text (cached per root and scope). */
 export function loadCatalog(root = skillRoot, { scope = 'runtime' } = {}) {
-  const key = `${root}\0${scope}`;
-  if (!cache.has(key)) cache.set(key, new Map(catalogEntries(root, { scope }).filter((e) => typeof e.en === 'string' && typeof e.vi === 'string').map((e) => [e.en, e.vi])));
-  return cache.get(key);
+    const key = `${root}\0${scope}`;
+    if (!cache.has(key))
+        cache.set(key, new Map(catalogEntries(root, { scope }).filter((e) => typeof e.en === 'string' && typeof e.vi === 'string').map((e) => [e.en, e.vi])));
+    return cache.get(key);
 }
-
-
 /** The names each `pattern` match captures (group 1) in `text`, in match order (`sort` sorts them). */
 export const captureNames = (text, pattern, { sort = false } = {}) => {
-  const names = [...String(text).matchAll(pattern)].map((m) => m[1]);
-  return sort ? names.sort(byCodeUnit) : names;
+    const names = [...String(text).matchAll(pattern)].map((m) => m[1]);
+    return sort ? names.sort(byCodeUnit) : names;
 };
-
 /** The names of the placeholders of a message. */
 export const placeholdersOf = (text) => captureNames(text, PLACEHOLDER, { sort: true });
-
 /** `text` with each `{name}` replaced by vars[name] (an unknown name is left as written). */
 export const fill = (text, vars = {}) => String(text).replace(PLACEHOLDER, (whole, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : whole));
-
 /** The message `en` in `language` (`vi` translates through the catalog; any other language is the English source). */
 export function translate(en, vars = {}, { language = DEFAULT_OWNER_LANGUAGE, root = skillRoot, scope = 'runtime' } = {}) {
-  const vi = language === 'vi' ? loadCatalog(root, { scope }).get(en) : undefined;
-  return fill(vi ?? en, vars);
+    const vi = language === 'vi' ? loadCatalog(root, { scope }).get(en) : undefined;
+    return fill(vi ?? en, vars);
 }
-
 /** The owner's language (config.yaml `language`); `fallback` when there is no readable config (DEFAULT_OWNER_LANGUAGE of engine/config.mjs). */
 export function ownerLanguage(fallback = DEFAULT_OWNER_LANGUAGE) {
-  try { return loadConfig()?.language ?? fallback; } catch { return fallback; }
+    try {
+        return loadConfig()?.language ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
 }
-
 /** A translator bound to one language: `tr(en, vars)`. */
-export const translator = (language = DEFAULT_OWNER_LANGUAGE, { root = skillRoot, scope = 'runtime' } = {}) =>
-  (en, vars = {}) => translate(en, vars, { language, root, scope });
-
+export const translator = (language = DEFAULT_OWNER_LANGUAGE, { root = skillRoot, scope = 'runtime' } = {}) => (en, vars = {}) => translate(en, vars, { language, root, scope });
 /**
  * A pattern source matching `en` in the owner's language or in English: each language's rendering of the English source,
  * escaped, with the placeholder `slot` (a placeholder name of `en`) replaced by `slotPattern`. Never hardcodes a spelling.
  */
-export const translatedPattern = (en, slot, slotPattern, languages = ['en', 'vi']) =>
-  `(?:${languages.map((language) => escapeRegExp(translate(en, { [slot]: '@@' }, { language })).replace('@@', slotPattern)).join('|')})`;
+export const translatedPattern = (en, slot, slotPattern, languages = ['en', 'vi']) => `(?:${languages.map((language) => escapeRegExp(translate(en, { [slot]: '@@' }, { language })).replace('@@', slotPattern)).join('|')})`;

package/runtime/scripts/lib/json-clone.mjs

@@ -2,52 +2,60 @@
 // copy of a value, detached from every reference, frozen state and class of the original. `structuredClone` keeps
 // what JSON drops (undefined members, Dates, Maps, sparse holes) and refuses what JSON accepts (functions,
 // `toJSON` objects), so it is not a substitute; this walks the value once under the JSON.stringify rules.
-
 /** The boxed primitives JSON.stringify unwraps: recognised by the internal slot a valueOf call reads, as JSON does. */
 const BOXED = [
-  { slot: Number.prototype.valueOf, read: Number },
-  { slot: String.prototype.valueOf, read: String },
-  { slot: Boolean.prototype.valueOf, read: (box) => Boolean.prototype.valueOf.call(box) },
-  { slot: BigInt.prototype.valueOf, read: (box) => BigInt.prototype.valueOf.call(box) },
+    { slot: Number.prototype.valueOf, read: Number },
+    { slot: String.prototype.valueOf, read: String },
+    { slot: Boolean.prototype.valueOf, read: (box) => Boolean.prototype.valueOf.call(box) },
+    { slot: BigInt.prototype.valueOf, read: (box) => BigInt.prototype.valueOf.call(box) },
 ];
-
 /** Whether `value` carries the internal slot `slot` reads (a valueOf of that boxed type does not throw on it). */
 const hasSlot = (slot, value) => {
-  try { slot.call(value); return true; } catch { return false; }
+    try {
+        slot.call(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
 };
-
 /** What JSON.stringify takes of `holder[key]`: the toJSON result when there is one, a boxed primitive unwrapped. */
 const serialized = (holder, key) => {
-  let value = holder[key];
-  if (value !== null && (typeof value === 'object' || typeof value === 'bigint') && typeof value.toJSON === 'function') value = value.toJSON(key);
-  if (value === null || typeof value !== 'object') return value;
-  const box = BOXED.find((candidate) => hasSlot(candidate.slot, value));
-  return box ? box.read(value) : value;
+    let value = holder[key];
+    if (value !== null && (typeof value === 'object' || typeof value === 'bigint') && typeof value.toJSON === 'function')
+        value = value.toJSON(key);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const box = BOXED.find((candidate) => hasSlot(candidate.slot, value));
+    return box ? box.read(value) : value;
 };
-
 /** A member JSON leaves out of an object (and writes as null in an array). */
 const isAbsent = (value) => value === undefined || typeof value === 'function' || typeof value === 'symbol';
-
 const copyValue = (value, ancestors) => {
-  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
-  if (typeof value === 'number') return Number.isFinite(value) ? value + 0 : null;
-  if (typeof value === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
-  if (ancestors.includes(value)) throw new TypeError('Converting circular structure to JSON');
-  const inside = [...ancestors, value];
-  if (Array.isArray(value)) {
-    return Array.from({ length: value.length }, (_, index) => {
-      const item = serialized(value, String(index));
-      return isAbsent(item) ? null : copyValue(item, inside);
-    });
-  }
-  const entries = [];
-  for (const name of Object.keys(value)) {
-    const member = serialized(value, name);
-    if (!isAbsent(member)) entries.push([name, copyValue(member, inside)]);
-  }
-  return Object.fromEntries(entries);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value + 0 : null;
+    if (typeof value === 'bigint')
+        throw new TypeError('Do not know how to serialize a BigInt');
+    if (ancestors.includes(value))
+        throw new TypeError('Converting circular structure to JSON');
+    const inside = [...ancestors, value];
+    if (Array.isArray(value)) {
+        return Array.from({ length: value.length }, (_, index) => {
+            const item = serialized(value, String(index));
+            return isAbsent(item) ? null : copyValue(item, inside);
+        });
+    }
+    const holder = value;
+    const entries = [];
+    for (const name of Object.keys(holder)) {
+        const member = serialized(holder, name);
+        if (!isAbsent(member))
+            entries.push([name, copyValue(member, inside)]);
+    }
+    return Object.fromEntries(entries);
 };
-
 /**
  * `value` copied as JSON data: members that are undefined, functions or symbols are dropped (an array item becomes
  * null), non-finite numbers become null and -0 becomes 0, `toJSON` results replace their objects (a Date becomes its ISO string), boxed
@@ -55,7 +63,8 @@ const copyValue = (value, ancestors) => {
  * a symbol) throws a SyntaxError, as parsing the missing text does.
  */
 export function jsonClone(value) {
-  const top = serialized({ '': value }, '');
-  if (isAbsent(top)) throw new SyntaxError('"undefined" is not valid JSON');
-  return copyValue(top, []);
+    const top = serialized({ '': value }, '');
+    if (isAbsent(top))
+        throw new SyntaxError('"undefined" is not valid JSON');
+    return copyValue(top, []);
 }

package/runtime/scripts/lib/json.mjs

@@ -2,31 +2,43 @@
 // truncated payload, so a malformed column is the caller's fallback, never a throw. The parse of the
 // literal 'null' is kept as null (callers that want {} instead write `parseJsonOr`).
 import { readParsedFile } from './read-text.mjs';
-
 /** `text` as JSON, or `fallback` when it does not parse. */
+// reason: JSON parsed from a ledger column or file is an untyped input boundary; each caller narrows what it reads.
 export const parseJson = (text, fallback = null) => {
-  try { return JSON.parse(text); } catch { return fallback; }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return fallback;
+    }
 };
-
 /** `text` as JSON, or `fallback` when it does not parse OR parses to null/undefined. Rows written
  * as the literal 'null' read back as the fallback too, so a caller that wants an object gets one. */
+// reason: same parsed-JSON boundary as parseJson.
 export const parseJsonOr = (text, fallback = {}) => parseJson(text) ?? fallback;
-
 /** A jobs/events row spread with `payload`: the row's payload_json parsed via parseJsonOr
  * (`fallback` defaults to {}). Pass fallback null to keep a raw parseJson result, nulls included. */
+// reason: same parsed-JSON boundary as parseJson.
 export const withPayload = (row, fallback = {}) => (row ? { ...row, payload: parseJsonOr(row.payload_json, fallback) } : row);
-
 /** `file` read and parsed as JSON, or `fallback` when the file is missing, unreadable or malformed. */
+// reason: same parsed-JSON boundary as parseJson.
 export const readJsonFile = (file, fallback = null) => readParsedFile(file, JSON.parse, fallback);
-
 /** `stdout` as JSON: the trimmed text, else its first-{-to-last-} span; null when neither parses. */
+// reason: same parsed-JSON boundary as parseJson.
 export const jsonFromStdout = (stdout) => {
-  const text = String(stdout ?? '').trim();
-  if (!text) return null;
-  try { return JSON.parse(text); } catch { /* fall through */ }
-  const first = text.indexOf('{'), last = text.lastIndexOf('}');
-  if (first >= 0 && last > first) {
-    try { return JSON.parse(text.slice(first, last + 1)); } catch { /* not json */ }
-  }
-  return null;
+    const text = String(stdout ?? '').trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch { /* fall through */ }
+    const first = text.indexOf('{'), last = text.lastIndexOf('}');
+    if (first >= 0 && last > first) {
+        try {
+            return JSON.parse(text.slice(first, last + 1));
+        }
+        catch { /* not json */ }
+    }
+    return null;
 };

package/runtime/scripts/lib/list.mjs

@@ -2,30 +2,25 @@
 // `v` when it already is an array, else []. Scalars are NOT wrapped: a caller that wants
 // `[v]` for a lone value writes its own coercion (see contract-version's list).
 export const list = (v) => (Array.isArray(v) ? v : []);
-
 /** `v` as an array: itself when already one, [] for null/undefined, else [v]. */
 export const asList = (v) => {
-  if (Array.isArray(v)) return v;
-  if (v == null) return [];
-  return [v];
+    if (Array.isArray(v))
+        return v;
+    if (v == null)
+        return [];
+    return [v];
 };
-
 /** The object entries of `v` (a non-array reads as []). */
 export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => item && typeof item === 'object');
-
 /** Every entry of `v` a non-empty string (`blank: false` also rejects all-whitespace entries). */
-export const stringList = (v, { blank = true } = {}) =>
-  Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
-
+export const stringList = (v, { blank = true } = {}) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
 /** A non-empty list of distinct values, all accepted by the supplied predicate. */
 export const nonemptyUniqueList = (values, accepts) => Array.isArray(values) && values.length > 0
-  && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
-
+    && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
 /** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
 export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
-  const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
-  return dedupe ? [...new Set(items)] : items;
+    const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
+    return dedupe ? [...new Set(items)] : items;
 };
-
 // The comparator of a bare `sort()` (UTF-16 code-unit order) is owned by the engine, which cannot import scripts/lib.
 export { byCodeUnit } from '../../engine/by-code-unit.mjs';