@starci/hfs 4.11.21 → 4.12.0

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/in-order.d.mts

@@ -0,0 +1,12 @@
+/** `for (const x of items) await fn(x, index)`: resolves undefined once every item has run, one at a time. */
+export declare const eachInOrder: <T>(items: Iterable<T>, fn: (item: T, index: number) => unknown) => Promise<undefined>;
+/** The sequential map: `fn(x, index)` for each item in turn, resolving the results in item order. */
+export declare const mapInOrder: <T, U>(items: Iterable<T>, fn: (item: T, index: number) => U | PromiseLike<U>) => Promise<U[]>;
+/** The first item whose `predicate(x, index)` resolves truthy (undefined when none); later items never run. */
+export declare const findInOrder: <T>(items: Iterable<T>, predicate: (item: T, index: number) => unknown) => Promise<T | undefined>;
+/**
+ * `for (;;) await step(attempt)`: `step(attempt)` runs again, after the previous run settled, until it resolves
+ * something other than undefined; that value (null included) is the result. A poll or retry returns undefined to go
+ * on and its answer to stop. `attempt` counts from 0.
+ */
+export declare const repeatInOrder: <R>(step: (attempt: number) => R | undefined | PromiseLike<R | undefined>) => Promise<R | undefined>;

package/runtime/scripts/lib/in-order.mjs

@@ -6,66 +6,85 @@
 // `for (const x of xs) await fn(x)` does. All of them run on the one `walk` below: promise callbacks, not an async
 // recursion, so the stack and the memory stay flat however long the input is.
 // Provably independent work that needs no order, short-circuit or error contract may use `Promise.all` instead.
-
 /** Close `iterator` the way a `for...of` leaves it: `return()` when it has one. */
 const close = (iterator) => iterator.return?.();
-
 /**
  * Drive `visit(item, index)` over `items` one at a time. `decide(outcome, item)` runs after each settled visit: a
  * `{ value }` box ends the walk with that value, anything else goes on. Resolves with the box value, or `undefined` when
  * the items ran out; rejects with the first rejection or throw, after closing the iterator.
  */
 const walk = (items, visit, decide) => new Promise((resolve, reject) => {
-  const iterator = items[Symbol.iterator]();
-  let index = 0;
-  const fail = (error) => {
-    try { close(iterator); } catch { /* the failure being reported wins, as it does in a for...of */ }
-    reject(error);
-  };
-  const stop = (value) => {
-    try { close(iterator); } catch (error) { reject(error); return; }
-    resolve(value);
-  };
-  const advance = () => {
-    let step, pending;
-    try {
-      step = iterator.next();
-      if (step.done) { resolve(undefined); return; }
-      pending = visit(step.value, index++);
-    } catch (error) {
-      if (step === undefined || step.done) reject(error); else fail(error);
-      return;
-    }
-    Promise.resolve(pending).then((outcome) => {
-      let box;
-      try { box = decide(outcome, step.value); } catch (error) { fail(error); return; }
-      if (box) stop(box.value); else advance();
-    }, fail);
-  };
-  advance();
+    const iterator = items[Symbol.iterator]();
+    let index = 0;
+    const fail = (error) => {
+        try {
+            close(iterator);
+        }
+        catch { /* the failure being reported wins, as it does in a for...of */ }
+        reject(error);
+    };
+    const stop = (value) => {
+        try {
+            close(iterator);
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        resolve(value);
+    };
+    const advance = () => {
+        let step, pending;
+        try {
+            step = iterator.next();
+            if (step.done) {
+                resolve(undefined);
+                return;
+            }
+            pending = visit(step.value, index++);
+        }
+        catch (error) {
+            if (step === undefined || step.done)
+                reject(error);
+            else
+                fail(error);
+            return;
+        }
+        const item = step.value;
+        Promise.resolve(pending).then((outcome) => {
+            let box;
+            try {
+                box = decide(outcome, item);
+            }
+            catch (error) {
+                fail(error);
+                return;
+            }
+            if (box)
+                stop(box.value);
+            else
+                advance();
+        }, fail);
+    };
+    advance();
 });
-
 const never = () => undefined;
-
 /** `for (const x of items) await fn(x, index)`: resolves undefined once every item has run, one at a time. */
 export const eachInOrder = (items, fn) => walk(items, fn, never);
-
 /** The sequential map: `fn(x, index)` for each item in turn, resolving the results in item order. */
 export const mapInOrder = (items, fn) => {
-  const results = [];
-  return walk(items, fn, (outcome) => { results.push(outcome); }).then(() => results);
+    const results = [];
+    return walk(items, fn, (outcome) => { results.push(outcome); return undefined; }).then(() => results);
 };
-
 /** The first item whose `predicate(x, index)` resolves truthy (undefined when none); later items never run. */
 export const findInOrder = (items, predicate) => walk(items, predicate, (outcome, item) => (outcome ? { value: item } : undefined));
-
 /**
  * `for (;;) await step(attempt)`: `step(attempt)` runs again, after the previous run settled, until it resolves
  * something other than undefined; that value (null included) is the result. A poll or retry returns undefined to go
  * on and its answer to stop. `attempt` counts from 0.
  */
 export const repeatInOrder = (step) => walk(forever(), step, (outcome) => (outcome === undefined ? undefined : { value: outcome }));
-
 function* forever() {
-  for (let attempt = 0; ; attempt++) yield attempt;
+    for (let attempt = 0;; attempt++)
+        yield attempt;
 }

package/runtime/scripts/lib/is-main.d.mts

@@ -0,0 +1,6 @@
+/**
+ * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
+ * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
+ * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
+ */
+export declare const isMain: (metaUrl: string, argv?: readonly (string | undefined)[]) => boolean;

package/runtime/scripts/lib/is-main.mjs

@@ -1,13 +1,20 @@
 // is-main.mjs - is this module the process entry point (`node file.mjs`, not an import)? Compared by real path.
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
-
+import { fileURLToPath } from 'node:url';
 /** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
-const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
+const realPathOf = (file) => { try {
+    return fs.realpathSync.native(path.resolve(file));
+}
+catch {
+    return path.resolve(file);
+} };
 /**
  * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
  * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
  * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
  */
-export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));
+export const isMain = (metaUrl, argv = process.argv) => {
+    const entry = argv[1];
+    return Boolean(entry) && realPathOf(entry) === realPathOf(fileURLToPath(metaUrl));
+};

package/runtime/scripts/lib/js-lex.d.mts

@@ -0,0 +1,32 @@
+/** One physical line of a comment: its text without the opener, and whether it is the first/last line of a block comment. */
+export interface LexComment {
+    line: number;
+    text: string;
+    first: boolean;
+    last: boolean;
+    block: boolean;
+}
+/** One string (or template piece): its line, its offset after the opening quote and its content. */
+export interface LexString {
+    line: number;
+    at: number;
+    text: string;
+}
+/** The three layers of a source. */
+export interface LexedSource {
+    code: string;
+    comments: LexComment[];
+    strings: LexString[];
+}
+/** The kind of source: stylesheet, stylesheet with line comments, or script. */
+export type LexLanguage = 'css' | 'scss' | 'script';
+/** What `kind` of source this is: `css` has block comments only, `scss` and `less` add line comments, anything else is script. */
+export declare const langOf: (file: string) => LexLanguage;
+/**
+ * `text` as { code, comments, strings }. `code` is the source with every comment, string and regular expression blanked (same length, same
+ * lines); `comments` are { line, text, first, last } per physical line of each comment (the text without its opener; `first` and `last`
+ * mark the ends of a block comment); `strings` are { line, at, text } per string or template piece, the content without its quotes and its offset.
+ */
+export declare const lexSource: (text?: unknown, lang?: string) => LexedSource;
+/** `text` as its physical lines (a line ends at \n, \r\n, \r, U+2028 and U+2029). */
+export declare const splitLines: (text?: unknown) => string[];