@rhost/testkit 1.5.1 → 1.5.2

package/node_modules/@ursamu/mushcode/src/analyze/commands.js

@@ -0,0 +1,29 @@
+import { findAll } from "../traverse/walk.js";
+import { print } from "../print/mod.js";
+/**
+ * Extract all DollarPattern and ListenPattern nodes from the tree, returning
+ * a flat list with the printed pattern text for easy display.
+ *
+ * Scans the entire tree so it works on CommandList roots and AttributeSet
+ * values alike.
+ */ export function extractCommands(root) {
+  const entries = [];
+  for (const node of findAll(root, "DollarPattern")){
+    entries.push({
+      type: "dollar",
+      patternText: print(node.pattern),
+      pattern: node.pattern,
+      action: node.action
+    });
+  }
+  for (const node of findAll(root, "ListenPattern")){
+    entries.push({
+      type: "listen",
+      patternText: print(node.pattern),
+      pattern: node.pattern,
+      action: node.action
+    });
+  }
+  return entries;
+}
+//# sourceMappingURL=commands.js.map

package/node_modules/@ursamu/mushcode/src/analyze/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sources":["./commands.ts"],"names":[],"mappings":"AACA,SAAS,OAAO,8BAAsC;AACtD,SAAS,KAAK,0BAAoC;AAclD;;;;;;CAMC,GACD,OAAO,SAAS,gBAAgB,IAAa;EAC3C,MAAM,UAA0B,EAAE;EAElC,KAAK,MAAM,QAAQ,QAAQ,MAAM,iBAAkB;IACjD,QAAQ,IAAI,CAAC;MACX,MAAa;MACb,aAAa,MAAM,KAAK,OAAO;MAC/B,SAAa,KAAK,OAAO;MACzB,QAAa,KAAK,MAAM;IAC1B;EACF;EAEA,KAAK,MAAM,QAAQ,QAAQ,MAAM,iBAAkB;IACjD,QAAQ,IAAI,CAAC;MACX,MAAa;MACb,aAAa,MAAM,KAAK,OAAO;MAC/B,SAAa,KAAK,OAAO;MACzB,QAAa,KAAK,MAAM;IAC1B;EACF;EAEA,OAAO;AACT"}

package/node_modules/@ursamu/mushcode/src/analyze/commands.ts

@@ -0,0 +1,46 @@
+import type { ASTNode }  from "../../parser/mod.ts";
+import { findAll }         from "../traverse/walk.js";
+import { print }           from "../print/mod.js";
+
+/** A `$command` or `^listen` pattern extracted from the AST. */
+export interface PatternEntry {
+  /** Whether this is a `$command` or `^listen` trigger. */
+  type:        "dollar" | "listen";
+  /** Printed form of the pattern for display (e.g., "+finger *"). */
+  patternText: string;
+  /** The raw pattern node (Pattern or PatternAlts). */
+  pattern:     ASTNode;
+  /** The action to execute when the pattern matches. */
+  action:      ASTNode;
+}
+
+/**
+ * Extract all DollarPattern and ListenPattern nodes from the tree, returning
+ * a flat list with the printed pattern text for easy display.
+ *
+ * Scans the entire tree so it works on CommandList roots and AttributeSet
+ * values alike.
+ */
+export function extractCommands(root: ASTNode): PatternEntry[] {
+  const entries: PatternEntry[] = [];
+
+  for (const node of findAll(root, "DollarPattern")) {
+    entries.push({
+      type:        "dollar",
+      patternText: print(node.pattern as ASTNode),
+      pattern:     node.pattern as ASTNode,
+      action:      node.action  as ASTNode,
+    });
+  }
+
+  for (const node of findAll(root, "ListenPattern")) {
+    entries.push({
+      type:        "listen",
+      patternText: print(node.pattern as ASTNode),
+      pattern:     node.pattern as ASTNode,
+      action:      node.action  as ASTNode,
+    });
+  }
+
+  return entries;
+}

package/node_modules/@ursamu/mushcode/src/analyze/deps.js

@@ -0,0 +1,45 @@
+import { findAll } from "../traverse/walk.js";
+import { print } from "../print/mod.js";
+/**
+ * Extract dependency edges from the tree: u() calls, @trigger commands, and
+ * get()/v() attribute reads.
+ *
+ * Targets are the printed form of the first argument (for function calls) or
+ * the object slot (for @trigger).  Dynamic targets (eval blocks) are included
+ * as-printed — the caller decides how to interpret them.
+ */ export function extractDeps(root) {
+  const deps = [];
+  for (const node of findAll(root, "FunctionCall")){
+    const name = node.name.toLowerCase();
+    const args = node.args;
+    if (args.length === 0) continue;
+    const target = print(args[0]);
+    if (name === "u") {
+      deps.push({
+        type: "u",
+        target
+      });
+    } else if (name === "get") {
+      deps.push({
+        type: "get",
+        target
+      });
+    } else if (name === "v") {
+      deps.push({
+        type: "get",
+        target
+      });
+    }
+  }
+  for (const node of findAll(root, "AtCommand")){
+    const name = node.name.toLowerCase();
+    if (name !== "trigger") continue;
+    if (!node.object) continue;
+    deps.push({
+      type: "trigger",
+      target: print(node.object)
+    });
+  }
+  return deps;
+}
+//# sourceMappingURL=deps.js.map

package/node_modules/@ursamu/mushcode/src/analyze/deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.js","sources":["./deps.ts"],"names":[],"mappings":"AACA,SAAS,OAAO,8BAAsC;AACtD,SAAS,KAAK,0BAAoC;AAclD;;;;;;;CAOC,GACD,OAAO,SAAS,YAAY,IAAa;EACvC,MAAM,OAAmB,EAAE;EAE3B,KAAK,MAAM,QAAQ,QAAQ,MAAM,gBAAiB;IAChD,MAAM,OAAO,AAAC,KAAK,IAAI,CAAY,WAAW;IAC9C,MAAM,OAAQ,KAAK,IAAI;IACvB,IAAI,KAAK,MAAM,KAAK,GAAG;IACvB,MAAM,SAAS,MAAM,IAAI,CAAC,EAAE;IAE5B,IAAI,SAAS,KAAK;MAChB,KAAK,IAAI,CAAC;QAAE,MAAM;QAAK;MAAO;IAChC,OAAO,IAAI,SAAS,OAAO;MACzB,KAAK,IAAI,CAAC;QAAE,MAAM;QAAO;MAAO;IAClC,OAAO,IAAI,SAAS,KAAK;MACvB,KAAK,IAAI,CAAC;QAAE,MAAM;QAAO;MAAO;IAClC;EACF;EAEA,KAAK,MAAM,QAAQ,QAAQ,MAAM,aAAc;IAC7C,MAAM,OAAO,AAAC,KAAK,IAAI,CAAY,WAAW;IAC9C,IAAI,SAAS,WAAW;IACxB,IAAI,CAAC,KAAK,MAAM,EAAE;IAClB,KAAK,IAAI,CAAC;MAAE,MAAM;MAAW,QAAQ,MAAM,KAAK,MAAM;IAAa;EACrE;EAEA,OAAO;AACT"}

package/node_modules/@ursamu/mushcode/src/analyze/deps.ts

@@ -0,0 +1,51 @@
+import type { ASTNode }  from "../../parser/mod.ts";
+import { findAll }         from "../traverse/walk.js";
+import { print }           from "../print/mod.js";
+
+/** A single dependency edge found in the softcode: a `u()` call, `@trigger`, or `get()`/`v()` read. */
+export interface DepEntry {
+  /**
+   * "u"       — u(attr, …) call (attribute function invocation)
+   * "trigger" — @trigger obj/attr=arg
+   * "get"     — get(obj/attr) or v(attr) read
+   */
+  type:   "u" | "trigger" | "get";
+  /** Printed target, e.g. "me/FN_FINGER", "#weather/ATTR", "[tag(db)]/ATTR". */
+  target: string;
+}
+
+/**
+ * Extract dependency edges from the tree: u() calls, @trigger commands, and
+ * get()/v() attribute reads.
+ *
+ * Targets are the printed form of the first argument (for function calls) or
+ * the object slot (for @trigger).  Dynamic targets (eval blocks) are included
+ * as-printed — the caller decides how to interpret them.
+ */
+export function extractDeps(root: ASTNode): DepEntry[] {
+  const deps: DepEntry[] = [];
+
+  for (const node of findAll(root, "FunctionCall")) {
+    const name = (node.name as string).toLowerCase();
+    const args  = node.args as ASTNode[];
+    if (args.length === 0) continue;
+    const target = print(args[0]);
+
+    if (name === "u") {
+      deps.push({ type: "u", target });
+    } else if (name === "get") {
+      deps.push({ type: "get", target });
+    } else if (name === "v") {
+      deps.push({ type: "get", target });
+    }
+  }
+
+  for (const node of findAll(root, "AtCommand")) {
+    const name = (node.name as string).toLowerCase();
+    if (name !== "trigger") continue;
+    if (!node.object) continue;
+    deps.push({ type: "trigger", target: print(node.object as ASTNode) });
+  }
+
+  return deps;
+}

package/node_modules/@ursamu/mushcode/src/analyze/mod.js

@@ -0,0 +1,18 @@
+/**
+ * @module
+ * Structural analysis of softcode: extract `$command`/`^listen` patterns,
+ * dependency edges (`u()`, `@trigger`, `get()`), and `#tagname` references.
+ *
+ * @example
+ * ```ts
+ * import { parse }           from "@ursamu/mushcode/parse";
+ * import { extractCommands } from "@ursamu/mushcode/analyze";
+ *
+ * const ast  = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+ * const cmds = extractCommands(ast);
+ * console.log(cmds[0].patternText); // "+finger *"
+ * ```
+ */ export { extractCommands } from "./commands.js";
+export { extractDeps } from "./deps.js";
+export { extractTagRefs } from "./tags.js";
+//# sourceMappingURL=mod.js.map

package/node_modules/@ursamu/mushcode/src/analyze/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sources":["./mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;CAcC,GAED,SAAS,eAAe,wBAAgD;AAExE,SAAS,WAAW,oBAAgD;AACpE,SAAS,cAAc,oBAA6C"}

package/node_modules/@ursamu/mushcode/src/analyze/mod.ts

@@ -0,0 +1,20 @@
+/**
+ * @module
+ * Structural analysis of softcode: extract `$command`/`^listen` patterns,
+ * dependency edges (`u()`, `@trigger`, `get()`), and `#tagname` references.
+ *
+ * @example
+ * ```ts
+ * import { parse }           from "@ursamu/mushcode/parse";
+ * import { extractCommands } from "@ursamu/mushcode/analyze";
+ *
+ * const ast  = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+ * const cmds = extractCommands(ast);
+ * console.log(cmds[0].patternText); // "+finger *"
+ * ```
+ */
+export type { PatternEntry }                      from "./commands.js";
+export { extractCommands }                         from "./commands.js";
+export type { DepEntry }                           from "./deps.js";
+export { extractDeps }                             from "./deps.js";
+export { extractTagRefs }                          from "./tags.js";

package/node_modules/@ursamu/mushcode/src/analyze/tags.js

@@ -0,0 +1,11 @@
+import { findAll } from "../traverse/walk.js";
+/**
+ * Return a deduplicated, sorted list of every tag name referenced by a `#tagname`
+ * TagRef node anywhere in the tree.
+ */ export function extractTagRefs(root) {
+  const names = findAll(root, "TagRef").map((n)=>n.name);
+  return [
+    ...new Set(names)
+  ].sort();
+}
+//# sourceMappingURL=tags.js.map

package/node_modules/@ursamu/mushcode/src/analyze/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sources":["./tags.ts"],"names":[],"mappings":"AACA,SAAS,OAAO,8BAAqC;AAErD;;;CAGC,GACD,OAAO,SAAS,eAAe,IAAa;EAC1C,MAAM,QAAQ,QAAQ,MAAM,UAAU,GAAG,CAAC,CAAA,IAAK,EAAE,IAAI;EACrD,OAAO;OAAI,IAAI,IAAI;GAAO,CAAC,IAAI;AACjC"}

package/node_modules/@ursamu/mushcode/src/analyze/tags.ts

@@ -0,0 +1,11 @@
+import type { ASTNode } from "../../parser/mod.ts";
+import { findAll }        from "../traverse/walk.js";
+
+/**
+ * Return a deduplicated, sorted list of every tag name referenced by a `#tagname`
+ * TagRef node anywhere in the tree.
+ */
+export function extractTagRefs(root: ASTNode): string[] {
+  const names = findAll(root, "TagRef").map(n => n.name as string);
+  return [...new Set(names)].sort();
+}

package/node_modules/@ursamu/mushcode/src/eval/context.js

@@ -0,0 +1,22 @@
+/**
+ * Create a default {@link EvalContext} with safe fallback values.
+ *
+ * Provide at minimum `enactor` and `executor` (usually the same UUID for
+ * top-level evaluations). All other fields default to safe empty values and a
+ * recursion limit of 100.
+ *
+ * @example
+ * const ctx = makeContext({ enactor: "player-uuid", executor: "player-uuid" });
+ */ export function makeContext(partial) {
+  return {
+    caller: null,
+    args: [],
+    registers: new Map(),
+    iterStack: [],
+    depth: 0,
+    maxDepth: 100,
+    maxOutputLen: 65_536,
+    ...partial
+  };
+}
+//# sourceMappingURL=context.js.map

package/node_modules/@ursamu/mushcode/src/eval/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sources":["./context.ts"],"names":[],"mappings":"AA6DA;;;;;;;;;CASC,GACD,OAAO,SAAS,YACd,OAAyE;EAEzE,OAAO;IACL,QAAW;IACX,MAAW,EAAE;IACb,WAAW,IAAI;IACf,WAAW,EAAE;IACb,OAAc;IACd,UAAc;IACd,cAAc;IACd,GAAG,OAAO;EACZ;AACF"}

package/node_modules/@ursamu/mushcode/src/eval/context.ts

@@ -0,0 +1,177 @@
+import type { ASTNode } from "../../parser/mod.ts";
+
+// ── Iteration state ───────────────────────────────────────────────────────────
+
+/** One frame on the iteration stack — pushed by iter(), map(), @dolist, etc. */
+export interface IterFrame {
+  item:  string;  // ## — current element value
+  index: number;  // #@ — current position (1-based)
+}
+
+// ── Custom substitution handlers ──────────────────────────────────────────────
+
+/** A custom substitution handler registered via `EvalEngine.registerSub()`. */
+export type SubHandlerFn = (code: string, ctx: EvalContext) => Promise<string> | string;
+
+// ── Command fallback handler ──────────────────────────────────────────────────
+
+/**
+ * A fallback handler called when an `@command` is executed but no specific
+ * handler is registered for that command name.
+ */
+export type CommandFallbackFn = (
+  name:     string,
+  switches: string[],
+  object:   string | null,
+  value:    string | null,
+  ctx:      EvalContext,
+  engine:   IEvalEngine,
+) => Promise<void>;
+
+// ── Evaluation context ────────────────────────────────────────────────────────
+
+/**
+ * Runtime state threaded through every eval call.
+ *
+ * `registers` is intentionally mutable — `setq()` writes to it and subsequent
+ * reads within the same attribute eval see the updated value.
+ */
+export interface EvalContext {
+  /** UUID of the enacting object — %# */
+  enactor:   string;
+  /** UUID of the executing object — %! */
+  executor:  string;
+  /** UUID of the calling object — %@ (null at the top level) */
+  caller:    string | null;
+  /** Positional arguments — %0 through %9 */
+  args:      string[];
+  /** Named registers — %q<name>.  setq() mutates this map. */
+  registers: Map<string, string>;
+  /** Iteration stack — ## and #@ resolve from iterStack[0] */
+  iterStack: IterFrame[];
+  /** Current recursion depth (incremented on each u() call) */
+  depth:     number;
+  /** Maximum allowed recursion depth before returning #-1 error */
+  maxDepth:     number;
+  /** Maximum total output length per evalString call (default 65 536) */
+  maxOutputLen: number;
+  /** Optional cancellation signal */
+  signal?:   AbortSignal;
+}
+
+/**
+ * Create a default {@link EvalContext} with safe fallback values.
+ *
+ * Provide at minimum `enactor` and `executor` (usually the same UUID for
+ * top-level evaluations). All other fields default to safe empty values and a
+ * recursion limit of 100.
+ *
+ * @example
+ * const ctx = makeContext({ enactor: "player-uuid", executor: "player-uuid" });
+ */
+export function makeContext(
+  partial: Partial<EvalContext> & Pick<EvalContext, "enactor" | "executor">,
+): EvalContext {
+  return {
+    caller:    null,
+    args:      [],
+    registers: new Map(),
+    iterStack: [],
+    depth:        0,
+    maxDepth:     100,
+    maxOutputLen: 65_536,
+    ...partial,
+  };
+}
+
+// ── Thunks (lazy arg evaluation) ──────────────────────────────────────────────
+
+/**
+ * A lazily-evaluated function argument.
+ * Call it to evaluate the underlying AST node in the current context.
+ * Pass a partial context override (e.g. `{ iterStack: [...] }`) to temporarily
+ * change evaluation state — used by iter() to set ## and #@.
+ */
+export type EvalThunk = (ctxOverride?: Partial<EvalContext>) => Promise<string>;
+
+// ── Database accessor ─────────────────────────────────────────────────────────
+
+/**
+ * Minimal read-only interface to the game database.
+ * Implement this in the host application and pass it to EvalEngine.
+ */
+export interface ObjectAccessor {
+  /** Read a named attribute from an object. Returns `null` if the attribute is absent. */
+  getAttr(objectId: string, attr: string): Promise<string | null>;
+  /** Resolve a target expression (`"me"`, `"#uuid"`, `"Name"`) to an object UUID. Returns `null` if not found. */
+  resolveTarget(from: string, expr: string): Promise<string | null>;
+  /** Return the display name of an object. */
+  getName(objectId: string): Promise<string>;
+  /** Return `true` if the object has the named flag. */
+  hasFlag(objectId: string, flag: string): Promise<boolean>;
+}
+
+// ── Function and command registrations ───────────────────────────────────────
+
+/**
+ * A registered softcode function.
+ *
+ * When `eval` is "eager" (default), all arguments are evaluated before `exec`
+ * is called and `args` contains `string[]`.
+ *
+ * When `eval` is "lazy", `args` contains `EvalThunk[]`.  The function calls
+ * only the thunks it needs (e.g. `if()` evaluates only the taken branch).
+ */
+export interface FunctionImpl {
+  /** Argument evaluation strategy. `"eager"` (default) pre-evaluates all args; `"lazy"` passes thunks. */
+  eval?:   "eager" | "lazy";
+  /** Minimum number of arguments required; fewer returns a `#-1` error. */
+  minArgs: number;
+  /** Maximum number of arguments accepted; more returns a `#-1` error. Use `Infinity` for variadic. */
+  maxArgs: number;
+  /** The function implementation. Receives `string[]` when eager, `EvalThunk[]` when lazy. */
+  exec: (
+    args:   string[] | EvalThunk[],
+    ctx:    EvalContext,
+    engine: IEvalEngine,
+  ) => Promise<string> | string;
+}
+
+/** A registered `@command` handler (e.g. `@pemit`, `@trigger`). */
+export interface CommandImpl {
+  /** Execute the command. `switches` are the `/switch` tokens; `object` and `value` are the two sides of `=`. */
+  exec: (
+    switches: string[],
+    object:   string | null,
+    value:    string | null,
+    ctx:      EvalContext,
+    engine:   IEvalEngine,
+  ) => Promise<void>;
+}
+
+// ── Engine interface (forward declaration for use in FunctionImpl/CommandImpl) ─
+
+/** Public interface of EvalEngine, used in function/command signatures. */
+export interface IEvalEngine {
+  /** The host-provided database accessor used by DB stdlib functions. */
+  readonly accessor: ObjectAccessor;
+  /** Register a softcode function (e.g. `add`, `u`) by name. */
+  registerFunction(name: string, impl: FunctionImpl): this;
+  /** Register a softcode `@command` handler by name. */
+  registerCommand(name: string, impl: CommandImpl): this;
+  /**
+   * Register a custom `%<code>` substitution handler.
+   * Custom handlers are checked before built-in substitutions.
+   */
+  registerSub(match: string | ((code: string) => boolean), fn: SubHandlerFn): this;
+  /**
+   * Register a fallback handler for `@commands` with no specific handler registered.
+   */
+  registerCommandFallback(fn: CommandFallbackFn): this;
+  /** Evaluate an AST node to a string. */
+  eval(node: ASTNode, ctx: EvalContext): Promise<string>;
+  /** Execute a node for its side effects (commands). */
+  exec(node: ASTNode, ctx: EvalContext): Promise<void>;
+  /** Parse and evaluate a raw softcode string. */
+  evalString(source: string, ctx: EvalContext): Promise<string>;
+}