@starci/eslint-grammar-offset-pop 0.12.13 → 0.13.0

package/runtime/scripts/lib/i18n.mjs

@@ -0,0 +1,85 @@
+// i18n.mjs - the ONE mechanism for text the owner must read in Vietnamese. Runtime source, comments and messages are English;
+// a message the owner reads (a Telegram notice, a why line, a progress report) is written once in English at its call site and
+// translated through a DECLARED catalog keyed from that English source: modules/i18n/messages/<area>.yaml, a list of
+// `{en, vi}` entries. Each area belongs to a scope: `runtime` for Node callers or `ui` for the generated browser catalog.
+// The `vi` field is declared in scripts/lib/language.mjs, so it is the only Vietnamese source. There is no per-module
+// `TEXT.vi` table and no second catalog mechanism.
+//
+//   const tr = translator(config.language);      // 'vi' translates, anything else returns the English source
+//   tr('Workflow {id} needs your decision', { id })
+//
+// A placeholder is `{name}`; the English and the Vietnamese of one entry carry exactly the same placeholders
+// (scripts/checks/check-i18n-catalog.mjs). An English source with no entry is returned as is: a missing translation degrades
+// to English, never to a blank.
+import { byCodeUnit } from './list.mjs';
+import { escapeRegExp } from './regex.mjs';
+import fs from 'node:fs';
+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 []; }
+}
+
+/** 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,
+    }));
+  });
+}
+
+/** 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);
+}
+
+
+/** 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;
+};
+
+/** 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);
+}
+
+/** 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; }
+}
+
+/** 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 });
+
+/**
+ * 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('|')})`;

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

@@ -0,0 +1,61 @@
+// json-clone.mjs — a deep copy that keeps exactly what survives a JSON text and nothing else: the plain-data
+// 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) },
+];
+
+/** 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; }
+};
+
+/** 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;
+};
+
+/** 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);
+};
+
+/**
+ * `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
+ * primitives unwrap, and a cycle or a BigInt throws a TypeError. A value JSON has no text for (undefined, a function,
+ * 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, []);
+}

package/runtime/scripts/lib/list.mjs

@@ -0,0 +1,31 @@
+// list.mjs — the array-or-empty coercion half the scripts re-declared by hand.
+// `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];
+};
+
+/** 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));
+
+/** 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;
+
+/** 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;
+};
+
+// 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';

package/runtime/scripts/lib/regex.mjs

@@ -0,0 +1,4 @@
+// regex.mjs - building a RegExp from text.
+
+/** `text` with every regular-expression metacharacter escaped, so it matches itself literally. */
+export const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);

package/runtime/scripts/lib/yaml-cached.mjs

@@ -0,0 +1,14 @@
+// yaml-cached.mjs - parse a YAML text once per distinct text in a process.
+//
+// The HFS slot manifest and rule catalog are large documents that one process asks for again at every check, every render and every fixture. Their
+// bytes do not change between those asks, so the parse (the dominant cost of a load) is keyed by the text itself; each caller gets its own copy of the
+// parsed document, so nothing a caller does to it reaches the next one. A changed file is a different text and parses again.
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const parsed = new Map();
+
+/** The parsed document of `text`: parsed on the first ask for this text, a structured copy afterwards. Throws what parseYaml throws, every time. */
+export function parseYamlCached(text) {
+  if (!parsed.has(text)) parsed.set(text, parseYaml(text));
+  return structuredClone(parsed.get(text));
+}