@rhost/testkit 1.5.0 → 1.5.2

package/node_modules/@ursamu/mushcode/_dist/src/traverse/transform.d.ts

@@ -0,0 +1,27 @@
+import type { ASTNode } from "../../parser/mod.js";
+/**
+ * A function called on each node, top-down.
+ *
+ * Return values:
+ *   `undefined`  — keep the node as-is and recurse into its children
+ *   `ASTNode`    — replace the node with this value, then recurse into it
+ *   `null`       — when in an array slot, remove the node from the array;
+ *                  when in a single slot, set the field to null
+ */ export type Transformer = (node: ASTNode) => ASTNode | null | undefined;
+/**
+ * Produce a new tree by applying `fn` to every node top-down.
+ *
+ * The function is called on each node before its children are processed.
+ * Returning a replacement node causes that replacement's children to be
+ * processed next (not the original children).
+ *
+ * The original tree is never mutated; a new object is returned whenever
+ * any node in the subtree changes.
+ *
+ * @example
+ * // Replace every TagRef with a Literal placeholder
+ * const out = transform(ast, (n) => {
+ *   if (n.type === "TagRef") return { type: "Literal", value: `<tag:${n.name}>` };
+ * });
+ */ export declare function transform(root: ASTNode, fn: Transformer): ASTNode;
+//# sourceMappingURL=transform.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/traverse/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sources":["../../../src/traverse/transform.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA8B;AAKnD;;;;;;;;CAQC,GACD,YAAY,eAAe,MAAM,YAAY,UAAU,IAAI,GAAG,SAAS;AAIvE;;;;;;;;;;;;;;;CAeC,GACD,OAAO,iBAAS,UAAU,MAAM,OAAO,EAAE,IAAI,WAAW,GAAG"}

package/node_modules/@ursamu/mushcode/_dist/src/traverse/walk.d.ts

@@ -0,0 +1,27 @@
+import type { ASTNode } from "../../parser/mod.js";
+/**
+ * Depth-first visitor hooks.
+ *
+ * `enter` is called before a node's children are visited.
+ *   Return `false` to skip all children of this node (leave is NOT called).
+ *
+ * `leave` is called after all children have been visited.
+ */ export interface Visitor {
+  /** Called before a node's children are visited. Return `false` to skip all children (and suppress `leave`). */ enter?: (node: ASTNode) => false | void;
+  /** Called after all children have been visited. */ leave?: (node: ASTNode) => void;
+}
+/**
+ * Walk an AST depth-first, calling visitor hooks at each node.
+ *
+ * @example
+ * const fnNames: string[] = [];
+ * walk(ast, {
+ *   enter(node) {
+ *     if (node.type === "FunctionCall") fnNames.push(node.name as string);
+ *   }
+ * });
+ */ export declare function walk(node: ASTNode, visitor: Visitor): void;
+/** Collect every node of the given type anywhere in the tree. */ export declare function findAll(root: ASTNode, type: string): ASTNode[];
+/** Return the first node of the given type, or `null` if none exists. */ export declare function findFirstOrNull(root: ASTNode, type: string): ASTNode | null;
+/** Return the first node of the given type, or throw if none exists. */ export declare function findFirst(root: ASTNode, type: string): ASTNode;
+//# sourceMappingURL=walk.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/traverse/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sources":["../../../src/traverse/walk.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA8B;AAKnD;;;;;;;CAOC,GACD,iBAAiB;EACf,6GAA6G,GAC7G,SAAS,MAAM,YAAY,KAAK,GAAG,IAAI;EACvC,iDAAiD,GACjD,SAAS,MAAM,YAAY,IAAI;;AAKjC;;;;;;;;;;CAUC,GACD,OAAO,iBAAS,KAAK,MAAM,OAAO,EAAE,SAAS,OAAO,GAAG,IAAI;AA+B3D,+DAA+D,GAC/D,OAAO,iBAAS,QAAQ,MAAM,OAAO,EAAE,MAAM,MAAM,GAAG;AAMtD,uEAAuE,GACvE,OAAO,iBAAS,gBAAgB,MAAM,OAAO,EAAE,MAAM,MAAM,GAAG,UAAU,IAAI;AAI5E,sEAAsE,GACtE,OAAO,iBAAS,UAAU,MAAM,OAAO,EAAE,MAAM,MAAM,GAAG"}

package/node_modules/@ursamu/mushcode/deno.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ursamu/mushcode",
+  "version": "0.3.4",
+  "description": "Parser, evaluator, linter, printer, and analyzer for MUX/RhostMUSH softcode.",
+  "license": "MIT",
+  "exports": {
+    ".":           "./mod.ts",
+    "./parse":     "./parser/mod.ts",
+    "./traverse":  "./src/traverse/mod.ts",
+    "./print":     "./src/print/mod.ts",
+    "./lint":      "./src/lint/mod.ts",
+    "./analyze":   "./src/analyze/mod.ts",
+    "./eval":      "./src/eval/mod.ts"
+  },
+  "tasks": {
+    "test":  "deno test --allow-read tests/",
+    "build": "npx peggy --format es --allowed-start-rules Start,LockExpr -o parser/mux-softcode.mjs grammar/mux-softcode.pegjs && npx peggy --allowed-start-rules Start,LockExpr -o parser/mux-softcode.js grammar/mux-softcode.pegjs"
+  },
+  "lint": {
+    "exclude": ["parser/mux-softcode.mjs", "parser/mux-softcode.js"]
+  },
+  "imports": {
+    "@std/assert":  "jsr:@std/assert@^1",
+    "@std/testing": "jsr:@std/testing@^1"
+  }
+}

package/node_modules/@ursamu/mushcode/deno.lock

@@ -0,0 +1,42 @@
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@std/assert@*": "1.0.19",
+    "jsr:@std/assert@1": "1.0.19",
+    "jsr:@std/assert@^1.0.17": "1.0.19",
+    "jsr:@std/internal@^1.0.12": "1.0.12",
+    "jsr:@std/path@*": "1.1.4",
+    "jsr:@std/testing@*": "1.0.17",
+    "jsr:@std/testing@1": "1.0.17"
+  },
+  "jsr": {
+    "@std/assert@1.0.19": {
+      "integrity": "eaada96ee120cb980bc47e040f82814d786fe8162ecc53c91d8df60b8755991e",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
+    "@std/internal@1.0.12": {
+      "integrity": "972a634fd5bc34b242024402972cd5143eac68d8dffaca5eaa4dba30ce17b027"
+    },
+    "@std/path@1.1.4": {
+      "integrity": "1d2d43f39efb1b42f0b1882a25486647cb851481862dc7313390b2bb044314b5",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
+    "@std/testing@1.0.17": {
+      "integrity": "87bdc2700fa98249d48a17cd72413352d3d3680dcfbdb64947fd0982d6bbf681",
+      "dependencies": [
+        "jsr:@std/assert@^1.0.17",
+        "jsr:@std/internal"
+      ]
+    }
+  },
+  "workspace": {
+    "dependencies": [
+      "jsr:@std/assert@1",
+      "jsr:@std/testing@1"
+    ]
+  }
+}

package/node_modules/@ursamu/mushcode/docs/analyze.md

@@ -0,0 +1,145 @@
+# Analyze
+
+```typescript
+import { extractCommands, extractDeps, extractTagRefs } from "jsr:@ursamu/mushcode/analyze";
+import type { PatternEntry, DepEntry } from "jsr:@ursamu/mushcode/analyze";
+```
+
+All three functions accept any `ASTNode` root and scan the entire subtree, so
+they work on `CommandList` roots, single `AttributeSet` values, or any other
+node type.
+
+## `extractCommands(root)`
+
+Return all `DollarPattern` (`$command`) and `ListenPattern` (`^listen`) nodes
+as a flat list with their printed pattern text.
+
+```typescript
+function extractCommands(root: ASTNode): PatternEntry[]
+```
+
+```typescript
+interface PatternEntry {
+  type:        "dollar" | "listen"; // which trigger kind
+  patternText: string;              // printed pattern, e.g. "+finger *"
+  pattern:     ASTNode;            // raw Pattern or PatternAlts node
+  action:      ASTNode;            // action expression node
+}
+```
+
+### Example
+
+```typescript
+import { parse }           from "jsr:@ursamu/mushcode/parse";
+import { extractCommands } from "jsr:@ursamu/mushcode/analyze";
+
+const src = `
+  $+finger *:@pemit %#=[u(me/FN_FINGER,%0)]
+  $+help:@pemit %#=[u(me/FN_HELP)]
+  ^* says *:@pemit %#=## said something
+`;
+
+const ast   = parse(src);
+const cmds  = extractCommands(ast);
+
+for (const cmd of cmds) {
+  console.log(`${cmd.type} "${cmd.patternText}"`);
+}
+// dollar "+finger *"
+// dollar "+help"
+// listen "* says *"
+```
+
+### Using the action node
+
+```typescript
+import { print }  from "jsr:@ursamu/mushcode/print";
+
+for (const cmd of cmds) {
+  console.log(`  action: ${print(cmd.action)}`);
+}
+```
+
+## `extractDeps(root)`
+
+Return dependency edges: `u()` attribute calls, `@trigger` commands, and
+`get()`/`v()` attribute reads.
+
+```typescript
+function extractDeps(root: ASTNode): DepEntry[]
+```
+
+```typescript
+interface DepEntry {
+  type:   "u" | "trigger" | "get"; // dependency kind
+  target: string;                  // printed first argument / object expression
+}
+```
+
+Dynamic targets (e.g. `u([r(0)]/ATTR)`) are included with their printed form;
+the caller decides how to interpret them.
+
+### Example
+
+```typescript
+import { parse }       from "jsr:@ursamu/mushcode/parse";
+import { extractDeps } from "jsr:@ursamu/mushcode/analyze";
+
+const ast  = parse("@pemit %#=[u(me/FN_A)][get(#room/DESC)];@trigger #target/EV=%0");
+const deps = extractDeps(ast);
+
+for (const dep of deps) {
+  console.log(`${dep.type}: ${dep.target}`);
+}
+// u: me/FN_A
+// get: #room/DESC
+// trigger: #target
+```
+
+### Building a dependency graph
+
+```typescript
+import { parse }           from "jsr:@ursamu/mushcode/parse";
+import { extractCommands } from "jsr:@ursamu/mushcode/analyze";
+import { extractDeps }     from "jsr:@ursamu/mushcode/analyze";
+
+function graphFor(src: string) {
+  const ast  = parse(src);
+  const cmds = extractCommands(ast);
+  return cmds.map(cmd => ({
+    pattern: cmd.patternText,
+    deps:    extractDeps(cmd.action),
+  }));
+}
+```
+
+## `extractTagRefs(root)`
+
+Return a deduplicated, sorted list of every tag name referenced by `#tagname`
+nodes anywhere in the tree.
+
+```typescript
+function extractTagRefs(root: ASTNode): string[]
+```
+
+### Example
+
+```typescript
+import { parse }          from "jsr:@ursamu/mushcode/parse";
+import { extractTagRefs } from "jsr:@ursamu/mushcode/analyze";
+
+const ast  = parse("[get(#room/DESC)][get(#room/NAME)][u(#db/FN)]");
+const tags = extractTagRefs(ast);
+console.log(tags); // ["db", "room"]  (deduplicated, sorted)
+```
+
+### Checking for unresolved tags
+
+```typescript
+const knownTags = new Set(["room", "db", "weather"]);
+const refs      = extractTagRefs(ast);
+const unknown   = refs.filter(tag => !knownTags.has(tag));
+if (unknown.length) {
+  console.warn("Unresolved tag refs:", unknown);
+}
+```

package/node_modules/@ursamu/mushcode/docs/eval.md

@@ -0,0 +1,312 @@
+# Eval
+
+```typescript
+import { EvalEngine, makeContext, registerStdlib } from "jsr:@ursamu/mushcode/eval";
+import type {
+  EvalContext, EvalThunk, ObjectAccessor, IEvalEngine,
+  FunctionImpl, CommandImpl, IterFrame,
+} from "jsr:@ursamu/mushcode/eval";
+```
+
+## Quick start
+
+```typescript
+import { EvalEngine, makeContext, registerStdlib } from "jsr:@ursamu/mushcode/eval";
+
+// 1. Implement ObjectAccessor against your database
+const accessor: ObjectAccessor = {
+  async getAttr(id, attr)         { return myDb.getAttr(id, attr); },
+  async resolveTarget(from, expr) { return myDb.resolve(from, expr); },
+  async getName(id)               { return myDb.getName(id); },
+  async hasFlag(id, flag)         { return myDb.hasFlag(id, flag); },
+};
+
+// 2. Create engine and load stdlib
+const engine = new EvalEngine(accessor);
+registerStdlib(engine);
+
+// 3. Build a context and evaluate
+const ctx    = makeContext({ enactor: "player-uuid", executor: "object-uuid" });
+const result = await engine.evalString("[add(1,2)]", ctx);
+console.log(result); // "3"
+```
+
+## `ObjectAccessor`
+
+The interface your host application must implement to connect the evaluator to
+your game database. All methods return Promises.
+
+```typescript
+interface ObjectAccessor {
+  /** Read a named attribute from an object. Returns null if absent. */
+  getAttr(objectId: string, attr: string): Promise<string | null>;
+
+  /** Resolve a target expression to a 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>;
+
+  /** Check whether an object has a flag. */
+  hasFlag(objectId: string, flag: string): Promise<boolean>;
+}
+```
+
+`resolveTarget` receives expressions like `"me"`, `"#uuid"`, `"ObjectName"`,
+or the printed form of an eval block. You decide how to resolve them.
+
+### Minimal in-memory implementation
+
+```typescript
+const objects = new Map([
+  ["uuid-1", { name: "Alice", attrs: new Map([["DESC", "A person."]]), flags: new Set(["CONNECTED"]) }],
+]);
+
+const accessor: ObjectAccessor = {
+  async getAttr(id, attr) {
+    return objects.get(id)?.attrs.get(attr.toUpperCase()) ?? null;
+  },
+  async resolveTarget(from, expr) {
+    if (expr === "me") return from;
+    for (const [id, obj] of objects) {
+      if (id === expr || obj.name === expr) return id;
+    }
+    return null;
+  },
+  async getName(id) {
+    return objects.get(id)?.name ?? "#-1 NO SUCH OBJECT";
+  },
+  async hasFlag(id, flag) {
+    return objects.get(id)?.flags.has(flag) ?? false;
+  },
+};
+```
+
+## `EvalEngine`
+
+```typescript
+class EvalEngine implements IEvalEngine {
+  constructor(accessor: ObjectAccessor)
+
+  registerFunction(name: string, impl: FunctionImpl): this
+  registerCommand(name: string, impl: CommandImpl): this
+
+  evalString(source: string, ctx: EvalContext): Promise<string>
+  eval(node: ASTNode, ctx: EvalContext): Promise<string>
+  exec(node: ASTNode, ctx: EvalContext): Promise<void>
+
+  readonly accessor: ObjectAccessor
+}
+```
+
+- `evalString` parses the source string and evaluates it.
+- `eval` evaluates an already-parsed `ASTNode` to a string.
+- `exec` executes a command node for its side effects (returns nothing).
+
+Methods are chainable via `registerFunction` / `registerCommand` return `this`.
+
+## `makeContext(partial)`
+
+Create an `EvalContext` with safe defaults. The `enactor` and `executor` fields
+are required; everything else is optional.
+
+```typescript
+function makeContext(
+  partial: Partial<EvalContext> & Pick<EvalContext, "enactor" | "executor">
+): EvalContext
+```
+
+```typescript
+// Minimal context
+const ctx = makeContext({ enactor: "player-1", executor: "player-1" });
+
+// With positional args and a register pre-set
+const ctx = makeContext({
+  enactor:   "player-1",
+  executor:  "object-5",
+  args:      ["sword", "shield"],
+  registers: new Map([["0", "initial"]]),
+  maxDepth:  50,
+});
+```
+
+## `EvalContext`
+
+```typescript
+interface EvalContext {
+  enactor:   string;           // %# — who triggered the action
+  executor:  string;           // %! — the object running the code
+  caller:    string | null;    // %@ — previous executor (null at top level)
+  args:      string[];         // %0–%9
+  registers: Map<string, string>; // %q<name>, mutated by setq()
+  iterStack: IterFrame[];      // ## and #@ — pushed/popped by iter()
+  depth:     number;           // current u() recursion depth
+  maxDepth:  number;           // recursion limit (default 100)
+  signal?:   AbortSignal;      // optional cancellation
+}
+```
+
+## `registerStdlib(engine)`
+
+Load all built-in softcode functions onto an engine instance.
+
+```typescript
+function registerStdlib(engine: IEvalEngine): void
+```
+
+Call this once after creating your engine. You can add custom functions before
+or after calling it.
+
+See [stdlib.md](stdlib.md) for the full function reference.
+
+## `FunctionImpl`
+
+Register a custom function:
+
+```typescript
+interface FunctionImpl {
+  eval?:   "eager" | "lazy"; // default: "eager"
+  minArgs: number;
+  maxArgs: number;
+  exec: (
+    args:   string[] | EvalThunk[],
+    ctx:    EvalContext,
+    engine: IEvalEngine,
+  ) => Promise<string> | string;
+}
+```
+
+### Eager function (default)
+
+Arguments are fully evaluated before `exec` is called. `args` is `string[]`.
+
+```typescript
+engine.registerFunction("double", {
+  minArgs: 1, maxArgs: 1,
+  exec(args) {
+    return String(Number((args as string[])[0]) * 2);
+  },
+});
+
+// [double(21)] → "42"
+```
+
+### Lazy function
+
+Arguments are passed as `EvalThunk[]`. The function calls only the thunks it
+needs. Required for short-circuit logic.
+
+```typescript
+engine.registerFunction("coalesce", {
+  eval:    "lazy",
+  minArgs: 1, maxArgs: Infinity,
+  async exec(args) {
+    for (const thunk of args as EvalThunk[]) {
+      const val = await thunk();
+      if (val !== "") return val;
+    }
+    return "";
+  },
+});
+```
+
+## `EvalThunk`
+
+```typescript
+type EvalThunk = (ctxOverride?: Partial<EvalContext>) => Promise<string>;
+```
+
+Calling a thunk evaluates its underlying AST node in the current context.
+Pass a partial context override to temporarily change evaluation state — this
+is how `iter()` sets `##` and `#@` without mutating the parent context.
+
+## `CommandImpl`
+
+Register a custom `@command`:
+
+```typescript
+interface CommandImpl {
+  exec: (
+    switches: string[],
+    object:   string | null,
+    value:    string | null,
+    ctx:      EvalContext,
+    engine:   IEvalEngine,
+  ) => Promise<void>;
+}
+```
+
+```typescript
+engine.registerCommand("pemit", {
+  async exec(switches, object, value, ctx, engine) {
+    if (!object || !value) return;
+    const targetId = await engine.accessor.resolveTarget(ctx.enactor, object);
+    if (!targetId) return;
+    const noeval = switches.includes("noeval");
+    const text   = noeval ? value : await engine.evalString(value, ctx);
+    await myGame.sendMessage(targetId, text);
+  },
+});
+```
+
+## `IterFrame`
+
+The structure pushed onto `ctx.iterStack` by `iter()` and similar functions.
+
+```typescript
+interface IterFrame {
+  item:  string; // ## — current element value
+  index: number; // #@ — current position (1-based)
+}
+```
+
+## Substitution codes
+
+The evaluator handles these `%X` substitutions from `EvalContext`:
+
+| Code            | Resolves to                             |
+|-----------------|-----------------------------------------|
+| `%0`–`%9`       | Positional args (`ctx.args[n]`)         |
+| `%q<name>`      | Named register (`ctx.registers`)        |
+| `%#`            | Enactor UUID                            |
+| `%:`            | Enactor UUID (object ID form)           |
+| `%!`            | Executor UUID                           |
+| `%@`            | Caller UUID (empty string if none)      |
+| `%+`            | Argument count                          |
+| `%r` / `%R`     | CRLF (`\r\n`)                           |
+| `%t` / `%T`     | Tab (`\t`)                              |
+| `%b` / `%B`     | Space                                   |
+| `%%`            | Literal `%`                             |
+| `%[` `%]`       | Literal `[` `]`                         |
+| `%,` `%;`       | Literal `,` `;`                         |
+| `%\\`           | Literal `\`                             |
+| `%N` / `%n`     | Enactor name (upper / lower)            |
+| `%L`            | Enactor location (via `resolveTarget`)  |
+| `%i0`–`%i9`     | Iter item at stack depth n              |
+| `%=ATTR`        | Enactor attribute shorthand             |
+| `%x` `%X` `%c` `%C` | ANSI pass-through (returned as-is) |
+
+Special variables (`##`, `#@`) resolve from `ctx.iterStack[0]`.
+
+## Cancellation
+
+Pass an `AbortSignal` to cancel long-running evaluations:
+
+```typescript
+const ac  = new AbortController();
+const ctx = makeContext({
+  enactor:  "player-1",
+  executor: "player-1",
+  signal:   ac.signal,
+});
+
+setTimeout(() => ac.abort(), 500);
+
+try {
+  const result = await engine.evalString(complexSrc, ctx);
+} catch (e) {
+  if (e instanceof DOMException && e.name === "AbortError") {
+    console.log("evaluation cancelled");
+  }
+}
+```