@rhost/testkit 1.5.1 → 1.5.2

package/node_modules/@ursamu/mushcode/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to JSR
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Run tests
+        run: deno task test
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # required for JSR OIDC publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Publish to JSR
+        run: deno publish

package/node_modules/@ursamu/mushcode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 UrsaMU Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@ursamu/mushcode/README.md

@@ -0,0 +1,110 @@
+# @ursamu/mushcode
+
+A MUX/RhostMUSH softcode toolkit for Deno and JSR. Parses softcode into an AST,
+evaluates it, lints it for common mistakes, prints it back to canonical text, and
+extracts structural information from it.
+
+## Installation
+
+```typescript
+import { parse, EvalEngine, lint, print, walk } from "jsr:@ursamu/mushcode";
+```
+
+Sub-path imports are available for tree-shaking:
+
+| Import path              | Exports                                                                                    |
+|--------------------------|--------------------------------------------------------------------------------------------|
+| `jsr:@ursamu/mushcode`   | everything below, combined                                                                 |
+| `…/parse`                | `parse`, `ParseError`, `ASTNode`, `SourceLocation`, `NodeType`, `StartRule`               |
+| `…/traverse`             | `walk`, `transform`, `findAll`, `findFirst`, `findFirstOrNull`                             |
+| `…/print`                | `print`, `PrintOptions`, `PrintMode`                                                       |
+| `…/lint`                 | `lint`, `RULES`, `Diagnostic`, `Severity`, `LintOptions`, `RuleId`                        |
+| `…/analyze`              | `extractCommands`, `extractDeps`, `extractTagRefs`, `PatternEntry`, `DepEntry`             |
+| `…/eval`                 | `EvalEngine`, `makeContext`, `registerStdlib`, `ObjectAccessor`, `EvalContext`, and more   |
+
+## Quick start
+
+### Parse
+
+```typescript
+import { parse, ParseError } from "jsr:@ursamu/mushcode";
+
+const ast = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+console.log(ast.type); // "DollarPattern"
+
+// Lock expressions use the second argument
+const lock = parse("flag^WIZARD|attr^STAFF:1", "LockExpr");
+```
+
+### Traverse
+
+```typescript
+import { parse, findAll } from "jsr:@ursamu/mushcode";
+
+const ast = parse("[add(1,[mul(2,3)])]");
+const calls = findAll(ast, "FunctionCall");
+console.log(calls.map(n => n.name)); // ["add", "mul"]
+```
+
+### Print
+
+```typescript
+import { parse, print } from "jsr:@ursamu/mushcode";
+
+const ast = parse("@pemit %#=Hello;@pemit %#=World");
+console.log(print(ast, { mode: "pretty" }));
+// @pemit %#=Hello
+// @pemit %#=World
+```
+
+### Lint
+
+```typescript
+import { parse, lint } from "jsr:@ursamu/mushcode";
+
+const ast = parse("$finger:@pemit %#=[u(me/FN)]");
+const diags = lint(ast);
+diags.forEach(d => console.log(`[${d.severity}] ${d.rule}: ${d.message}`));
+```
+
+### Analyze
+
+```typescript
+import { parse, extractCommands } from "jsr:@ursamu/mushcode";
+
+const ast  = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+const cmds = extractCommands(ast);
+console.log(cmds[0].patternText); // "+finger *"
+```
+
+### Evaluate
+
+```typescript
+import { EvalEngine, makeContext, registerStdlib } from "jsr:@ursamu/mushcode";
+
+const engine = new EvalEngine({
+  async getAttr(id, attr)            { return null; },
+  async resolveTarget(from, expr)    { return expr === "me" ? from : null; },
+  async getName(id)                  { return "Tester"; },
+  async hasFlag(id, flag)            { return false; },
+});
+registerStdlib(engine);
+
+const ctx    = makeContext({ enactor: "player-uuid", executor: "player-uuid" });
+const result = await engine.evalString("[add(1,2)] [capstr(hello)]", ctx);
+console.log(result); // "3 Hello"
+```
+
+## Documentation
+
+- [Parser](docs/parser.md) — `parse()`, AST node types, source locations
+- [Traverse](docs/traverse.md) — `walk()`, `transform()`, `findAll()`, `findFirst()`
+- [Print](docs/print.md) — `print()`, compact and pretty modes
+- [Lint](docs/lint.md) — `lint()`, built-in rules, custom rule selection
+- [Analyze](docs/analyze.md) — `extractCommands()`, `extractDeps()`, `extractTagRefs()`
+- [Eval](docs/eval.md) — `EvalEngine`, `makeContext()`, `ObjectAccessor`
+- [Stdlib](docs/stdlib.md) — all built-in softcode functions
+
+## License
+
+MIT

package/node_modules/@ursamu/mushcode/_dist/mod.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module
+ * Full-featured MUX/RhostMUSH softcode toolkit: parser, AST traversal,
+ * canonical printer, static linter, dependency analyzer, and evaluator.
+ *
+ * @example
+ * ```ts
+ * import { parse, lint, print, EvalEngine, makeContext, registerStdlib } from "@ursamu/mushcode";
+ *
+ * const ast   = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+ * const diags = lint(ast);
+ * console.log(print(ast)); // "$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]"
+ *
+ * const engine = new EvalEngine({
+ *   getAttr: async (_id, _attr) => null,
+ *   resolveTarget: async (_from, expr) => expr === "me" ? "player-uuid" : null,
+ *   getName: async (_id) => "Tester",
+ *   hasFlag: async (_id, _flag) => false,
+ * });
+ * registerStdlib(engine);
+ * const result = await engine.evalString("[add(1,2)]", makeContext({ enactor: "player-uuid", executor: "player-uuid" }));
+ * console.log(result); // "3"
+ * ```
+ */ export { parse, ParseError } from "./parser/mod.js";
+export type { ASTNode, NodeType, StartRule, SourceLocation, SourcePosition } from "./parser/mod.js";
+export { walk, transform, findAll, findFirst, findFirstOrNull } from "./src/traverse/mod.js";
+export type { Visitor, Transformer } from "./src/traverse/mod.js";
+export { print } from "./src/print/mod.js";
+export type { PrintOptions, PrintMode } from "./src/print/mod.js";
+export { lint, RULES } from "./src/lint/mod.js";
+export type { Diagnostic, Severity, LintOptions, RuleId } from "./src/lint/mod.js";
+export { extractCommands, extractDeps, extractTagRefs } from "./src/analyze/mod.js";
+export type { PatternEntry, DepEntry } from "./src/analyze/mod.js";
+export { EvalEngine, makeContext, registerStdlib } from "./src/eval/mod.js";
+export type { EvalContext, EvalThunk, ObjectAccessor, IEvalEngine, FunctionImpl, CommandImpl, IterFrame } from "./src/eval/mod.js";
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAWD,SAAS,KAAK,EAAE,UAAU,0BAAiD;AAC3E,cAAc,OAAO,EAAE,QAAQ,EAAE,SAAS,EAC5B,cAAc,EAAE,cAAc,0BAA+B;AAG3E,SAAS,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,gCACoB;AACjF,cAAc,OAAO,EAAE,WAAW,gCAA+C;AAGjF,SAAS,KAAK,6BAAgE;AAC9E,cAAc,YAAY,EAAE,SAAS,6BAAyC;AAG9E,SAAS,IAAI,EAAE,KAAK,4BAAyD;AAC7E,cAAc,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,4BACsB;AAG7E,SAAS,eAAe,EAAE,WAAW,EAAE,cAAc,+BAC2B;AAChF,cAAc,YAAY,EAAE,QAAQ,+BAA4C;AAGhF,SAAS,UAAU,EAAE,WAAW,EAAE,cAAc,4BAA6B;AAC7E,cACE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EACnD,YAAY,EAAE,WAAW,EAAE,SAAS,4BACuC"}

package/node_modules/@ursamu/mushcode/_dist/parser/mod.d.ts

@@ -0,0 +1,41 @@
+/** Union of every node `type` string the parser can produce. */ export type NodeType = "Literal" | "Escape" | "Substitution" | "SpecialVar" | "Wildcard" | "EvalBlock" | "BracedString" | "Text" | "Arg" | "FunctionCall" | "DollarPattern" | "ListenPattern" | "PatternAlts" | "Pattern" | "CommandList" | "AtCommand" | "AttributeSet" | "UserCommand" | "TagRef" | "LockOr" | "LockAnd" | "LockNot" | "LockMe" | "LockDbref" | "LockFlagCheck" | "LockTypeCheck" | "LockAttrCheck" | "LockPlayerName";
+/** A character offset, line number (1-based), and column (1-based) in source text. */ export interface SourcePosition {
+  /** Zero-based byte offset from the start of the source string. */ offset: number;
+  /** One-based line number. */ line: number;
+  /** One-based column number within the line. */ column: number;
+}
+/** The start and end {@link SourcePosition} of an AST node in the original source. */ export interface SourceLocation {
+  /** Position of the first character of the node. */ start: SourcePosition;
+  /** Position one past the last character of the node. */ end: SourcePosition;
+}
+/**
+ * A generic AST node.  Every node has a `type` discriminant string and an
+ * optional `loc` source location.  Additional properties are node-specific
+ * (e.g. `value` on Literal, `name` on FunctionCall).
+ */ export type ASTNode = {
+  type: string;
+  loc?: SourceLocation;
+  [key: string]: any;
+};
+/** Thrown when the parser encounters a syntax error in the softcode input. */ export declare class ParseError extends Error {
+  readonly location?: {
+    line: number;
+    column: number;
+    offset: number;
+  };
+  constructor(message: string, location?: {
+    line: number;
+    column: number;
+    offset: number;
+  });
+}
+/** Which top-level grammar rule to use as the parse entry point. */ export type StartRule = "Start" | "LockExpr";
+/**
+ * Parse a raw softcode string and return its AST root node.
+ *
+ * @param text      The softcode source to parse.
+ * @param startRule Grammar entry point — `"Start"` for normal softcode (default),
+ *                  `"LockExpr"` for lock-expression strings.
+ * @throws {@link ParseError} on syntax errors.
+ */ export declare function parse(text: string, startRule?: StartRule): ASTNode;
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/parser/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../parser/mod.ts"],"names":[],"mappings":"AA2BA,8DAA8D,GAC9D,YAAY,WACR,YAAY,WAAW,iBAAiB,eAAe,aACvD,cAAc,iBAAiB,SAAS,QACxC,iBAAiB,kBAAkB,kBACnC,gBAAgB,YAChB,gBAAgB,cAAc,iBAAiB,gBAC/C,WACA,WAAW,YAAY,YAAY,WAAW,cAC9C,kBAAkB,kBAAkB,kBAAkB;AAE1D,oFAAoF,GACpF,iBAAiB;EACf,gEAAgE,GAChE,QAAQ,MAAM;EACd,2BAA2B,GAC3B,MAAQ,MAAM;EACd,6CAA6C,GAC7C,QAAQ,MAAM;;AAGhB,oFAAoF,GACpF,iBAAiB;EACf,iDAAiD,GACjD,OAAO;EACP,sDAAsD,GACtD,KAAO;;AAGT;;;;CAIC,GAED,YAAY;EAAY,MAAM,MAAM;EAAE,MAAM;GAAiB,KAAK,MAAM,GAAG,GAAG;;AAE9E,4EAA4E,GAC5E,OAAO,cAAM,mBAAmB;WAGZ;IAAa,MAAM,MAAM;IAAE,QAAQ,MAAM;IAAE,QAAQ,MAAM;;EAF3E,YACE,SAAS,MAAM,EACf,AAAgB;IAAa,MAAM,MAAM;IAAE,QAAQ,MAAM;IAAE,QAAQ,MAAM;GAAE;AAK/E;AAEA,kEAAkE,GAClE,YAAY,YAAY,UAAU;AAElC;;;;;;;CAOC,GACD,OAAO,iBAAS,MAAM,MAAM,MAAM,EAAE,YAAW,SAAmB,GAAG"}

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

@@ -0,0 +1,15 @@
+import type { ASTNode } from "../../parser/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 declare function extractCommands(root: ASTNode): PatternEntry[];
+//# sourceMappingURL=commands.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/analyze/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sources":["../../../src/analyze/commands.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA+B;AAIpD,8DAA8D,GAC9D,iBAAiB;EACf,uDAAuD,GACvD,MAAa,WAAW;EACxB,iEAAiE,GACjE,aAAa,MAAM;EACnB,mDAAmD,GACnD,SAAa;EACb,oDAAoD,GACpD,QAAa;;AAGf;;;;;;CAMC,GACD,OAAO,iBAAS,gBAAgB,MAAM,OAAO,GAAG"}

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

@@ -0,0 +1,18 @@
+import type { ASTNode } from "../../parser/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 declare function extractDeps(root: ASTNode): DepEntry[];
+//# sourceMappingURL=deps.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/analyze/deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.d.ts","sources":["../../../src/analyze/deps.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA+B;AAIpD,qGAAqG,GACrG,iBAAiB;EACf;;;;GAIC,GACD,MAAQ,MAAM,YAAY;EAC1B,4EAA4E,GAC5E,QAAQ,MAAM;;AAGhB;;;;;;;CAOC,GACD,OAAO,iBAAS,YAAY,MAAM,OAAO,GAAG"}

package/node_modules/@ursamu/mushcode/_dist/src/analyze/mod.d.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";
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/analyze/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../../src/analyze/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;CAcC,GACD,cAAc,YAAY,wBAA6C;AACvE,SAAS,eAAe,wBAAgD;AACxE,cAAc,QAAQ,oBAA8C;AACpE,SAAS,WAAW,oBAAgD;AACpE,SAAS,cAAc,oBAA6C"}

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

@@ -0,0 +1,6 @@
+import type { ASTNode } from "../../parser/mod.js";
+/**
+ * Return a deduplicated, sorted list of every tag name referenced by a `#tagname`
+ * TagRef node anywhere in the tree.
+ */ export declare function extractTagRefs(root: ASTNode): string[];
+//# sourceMappingURL=tags.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/analyze/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sources":["../../../src/analyze/tags.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA8B;AAGnD;;;CAGC,GACD,OAAO,iBAAS,eAAe,MAAM,OAAO,GAAG,MAAM"}

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

@@ -0,0 +1,85 @@
+import type { ASTNode } from "../../parser/mod.js";
+/** One frame on the iteration stack — pushed by iter(), map(), @dolist, etc. */ export interface IterFrame {
+  item: string;
+  index: number;
+}
+/** A custom substitution handler registered via `EvalEngine.registerSub()`. */ export type SubHandlerFn = (code: string, ctx: EvalContext) => Promise<string> | string;
+/**
+ * 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>;
+/**
+ * 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 declare function makeContext(partial: Partial<EvalContext> & Pick<EvalContext, "enactor" | "executor">): EvalContext;
+/**
+ * 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>;
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/** 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>;
+}
+//# sourceMappingURL=context.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/eval/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sources":["../../../src/eval/context.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA8B;AAInD,8EAA8E,GAC9E,iBAAiB;EACf,MAAO,MAAM;EACb,OAAO,MAAM;;AAKf,6EAA6E,GAC7E,YAAY,gBAAgB,MAAM,MAAM,EAAE,KAAK,gBAAgB,QAAQ,MAAM,IAAI,MAAM;AAIvF;;;CAGC,GACD,YAAY,qBACV,MAAU,MAAM,EAChB,UAAU,MAAM,IAChB,QAAU,MAAM,GAAG,IAAI,EACvB,OAAU,MAAM,GAAG,IAAI,EACvB,KAAU,aACV,QAAU,gBACP,QAAQ,IAAI;AAIjB;;;;;CAKC,GACD,iBAAiB;EACf,qCAAqC,GACrC,SAAW,MAAM;EACjB,sCAAsC,GACtC,UAAW,MAAM;EACjB,4DAA4D,GAC5D,QAAW,MAAM,GAAG,IAAI;EACxB,yCAAyC,GACzC,MAAW,MAAM;EACjB,0DAA0D,GAC1D,WAAW,IAAI,MAAM,EAAE,MAAM;EAC7B,0DAA0D,GAC1D,WAAW;EACX,2DAA2D,GAC3D,OAAW,MAAM;EACjB,+DAA+D,GAC/D,UAAc,MAAM;EACpB,qEAAqE,GACrE,cAAc,MAAM;EACpB,iCAAiC,GACjC,SAAW;;AAGb;;;;;;;;;CASC,GACD,OAAO,iBAAS,YACd,SAAS,QAAQ,eAAe,KAAK,aAAa,YAAY,WAAW,GACxE;AAeH;;;;;CAKC,GACD,YAAY,aAAa,cAAc,QAAQ,iBAAiB,QAAQ,MAAM;AAI9E;;;CAGC,GACD,iBAAiB;EACf,sFAAsF,GACtF,QAAQ,UAAU,MAAM,EAAE,MAAM,MAAM,GAAG,QAAQ,MAAM,GAAG,IAAI;EAC9D,8GAA8G,GAC9G,cAAc,MAAM,MAAM,EAAE,MAAM,MAAM,GAAG,QAAQ,MAAM,GAAG,IAAI;EAChE,0CAA0C,GAC1C,QAAQ,UAAU,MAAM,GAAG,QAAQ,MAAM;EACzC,oDAAoD,GACpD,QAAQ,UAAU,MAAM,EAAE,MAAM,MAAM,GAAG,QAAQ,OAAO;;AAK1D;;;;;;;;CAQC,GACD,iBAAiB;EACf,sGAAsG,GACtG,OAAS,UAAU;EACnB,uEAAuE,GACvE,SAAS,MAAM;EACf,mGAAmG,GACnG,SAAS,MAAM;EACf,0FAA0F,GAC1F,OACE,MAAQ,MAAM,KAAK,aACnB,KAAQ,aACR,QAAQ,gBACL,QAAQ,MAAM,IAAI,MAAM;;AAG/B,iEAAiE,GACjE,iBAAiB;EACf,6GAA6G,GAC7G,OACE,UAAU,MAAM,IAChB,QAAU,MAAM,GAAG,IAAI,EACvB,OAAU,MAAM,GAAG,IAAI,EACvB,KAAU,aACV,QAAU,gBACP,QAAQ,IAAI;;AAKnB,yEAAyE,GACzE,iBAAiB;EACf,qEAAqE,YAC5D,UAAU;EACnB,4DAA4D,GAC5D,iBAAiB,MAAM,MAAM,EAAE,MAAM,eAAe,IAAI;EACxD,oDAAoD,GACpD,gBAAgB,MAAM,MAAM,EAAE,MAAM,cAAc,IAAI;EACtD;;;GAGC,GACD,YAAY,OAAO,MAAM,KAAK,MAAM,MAAM,KAAK,OAAO,GAAG,IAAI,eAAe,IAAI;EAChF;;GAEC,GACD,wBAAwB,IAAI,oBAAoB,IAAI;EACpD,sCAAsC,GACtC,KAAK,MAAM,SAAS,KAAK,cAAc,QAAQ,MAAM;EACrD,oDAAoD,GACpD,KAAK,MAAM,SAAS,KAAK,cAAc,QAAQ,IAAI;EACnD,8CAA8C,GAC9C,WAAW,QAAQ,MAAM,EAAE,KAAK,cAAc,QAAQ,MAAM"}

package/node_modules/@ursamu/mushcode/_dist/src/eval/engine.d.ts

@@ -0,0 +1,48 @@
+import type { ASTNode } from "../../parser/mod.js";
+import type { EvalContext, FunctionImpl, CommandImpl, ObjectAccessor, IEvalEngine, SubHandlerFn, CommandFallbackFn } from "./context.js";
+/**
+ * AST-based softcode evaluator.
+ *
+ * Register functions and commands, then call `evalString()` to evaluate a
+ * raw softcode string or `eval()` to evaluate an already-parsed node.
+ *
+ * @example
+ * const engine = new EvalEngine(myAccessor);
+ * registerStdlib(engine);
+ * engine.registerFunction("u", { eval: "lazy", minArgs: 1, maxArgs: Infinity, exec: uImpl });
+ * const result = await engine.evalString("[add(1,2)]", ctx);
+ * // → "3"
+ */ export declare class EvalEngine implements IEvalEngine {
+  readonly accessor: ObjectAccessor;
+  private readonly functions: any;
+  private readonly commands: any;
+  private readonly subHandlers: any;
+  private fallbackCommand?: any;
+  constructor(/** The host-provided database accessor (passed to DB stdlib functions). */ accessor: ObjectAccessor);
+  /** Register a softcode function by name (case-insensitive). Returns `this` for chaining. */ registerFunction(name: string, impl: FunctionImpl): this;
+  /** Register a `@command` handler by name (case-insensitive). Returns `this` for chaining. */ registerCommand(name: string, impl: CommandImpl): this;
+  /**
+   * Register a custom `%<code>` substitution handler.
+   *
+   * Custom handlers are checked **before** built-in substitutions, so you can
+   * override any built-in code. `match` is either an exact code string (e.g.
+   * `"s"` for `%s`) or a predicate (e.g. `code => code.startsWith("V")` for
+   * `%Va`–`%Vz`).
+   *
+   * @returns `this` for chaining.
+   */ registerSub(match: string | ((code: string) => boolean), fn: SubHandlerFn): this;
+  /**
+   * Register a fallback handler for `@commands` that have no specific handler registered.
+   *
+   * @returns `this` for chaining.
+   */ registerCommandFallback(fn: CommandFallbackFn): this;
+  /** Parse and evaluate a raw softcode string. */ evalString(source: string, ctx: EvalContext): Promise<string>;
+  /** Evaluate a 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>;
+  private evalParts: any;
+  private evalFunction: any;
+  private evalSub: any;
+  private evalSpecialVar: any;
+  private resolveLocation: any;
+}
+//# sourceMappingURL=engine.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/eval/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sources":["../../../src/eval/engine.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAAkC;AAEvD,cACE,WAAW,EACX,YAAY,EAAE,WAAW,EACzB,cAAc,EAAE,WAAW,EAChB,YAAY,EAAE,iBAAiB,uBACtB;AAItB;;;;;;;;;;;;CAYC,GACD,OAAO,cAAM,sBAAsB;WAQtB,UAAU;EAPrB,iBAAiB,eAA8C;EAC/D,iBAAiB,cAA6C;EAC9D,iBAAiB,iBAA2F;EAC5G,QAAQ,sBAAoC;EAE5C,YACE,yEAAyE,GACzE,AAAS,UAAU,cAAc;EAGnC,0FAA0F,GAC1F,iBAAiB,MAAM,MAAM,EAAE,MAAM,YAAY,GAAG,IAAI;EAKxD,2FAA2F,GAC3F,gBAAgB,MAAM,MAAM,EAAE,MAAM,WAAW,GAAG,IAAI;EAKtD;;;;;;;;;GASC,GACD,YACE,OAAO,MAAM,KAAK,MAAM,MAAM,KAAK,OAAO,CAAC,EAC3C,IAAI,YAAY,GACf,IAAI;EAKP;;;;GAIC,GACD,wBAAwB,IAAI,iBAAiB,GAAG,IAAI;EAKpD,8CAA8C,GAC9C,AAAM,WAAW,QAAQ,MAAM,EAAE,KAAK,WAAW,GAAG,QAAQ,MAAM;EAOlE,iCAAiC,GACjC,AAAM,KAAK,MAAM,OAAO,EAAE,KAAK,WAAW,GAAG,QAAQ,MAAM;EA8C3D,oDAAoD,GACpD,AAAM,KAAK,MAAM,OAAO,EAAE,KAAK,WAAW,GAAG,QAAQ,IAAI;UA0C3C;UAYA;UA8BA;UA4CN;UAQM;AAQhB"}

package/node_modules/@ursamu/mushcode/_dist/src/eval/mod.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module
+ * AST-based softcode evaluator: `EvalEngine`, `makeContext()`, `registerStdlib()`,
+ * and the full type vocabulary for contexts, accessors, and function registrations.
+ *
+ * @example
+ * ```ts
+ * import { EvalEngine, makeContext, registerStdlib } from "@ursamu/mushcode/eval";
+ *
+ * const engine = new EvalEngine({
+ *   getAttr: async (_id, _attr) => null,
+ *   resolveTarget: async (_from, expr) => expr === "me" ? "player-uuid" : null,
+ *   getName: async (_id) => "Tester",
+ *   hasFlag: async (_id, _flag) => false,
+ * });
+ * registerStdlib(engine);
+ *
+ * const ctx    = makeContext({ enactor: "player-uuid", executor: "player-uuid" });
+ * const result = await engine.evalString("[add(1,2)] [capstr(hello)]", ctx);
+ * console.log(result); // "3 Hello"
+ * ```
+ */ export { EvalEngine } from "./engine.js";
+export { makeContext } from "./context.js";
+export { registerStdlib } from "./stdlib/mod.js";
+export type { EvalContext, EvalThunk, ObjectAccessor, IEvalEngine, FunctionImpl, CommandImpl, IterFrame, SubHandlerFn, CommandFallbackFn } from "./context.js";
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/eval/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../../src/eval/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,SAAS,UAAU,sBAA+B;AAClD,SAAS,WAAW,uBAA+B;AACnD,SAAS,cAAc,0BAA+B;AACtD,cACE,WAAW,EAAE,SAAS,EACtB,cAAc,EAAE,WAAW,EAC3B,YAAY,EAAE,WAAW,EACzB,SAAS,EAAE,YAAY,EAAE,iBAAiB,uBACO"}

package/node_modules/@ursamu/mushcode/_dist/src/eval/stdlib/mod.d.ts

@@ -0,0 +1,3 @@
+import type { IEvalEngine } from "../context.js";
+/** Register the full standard softcode function library on an engine. */ export declare function registerStdlib(engine: IEvalEngine): void;
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/eval/stdlib/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../../../src/eval/stdlib/mod.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,wBAAwB;AASjD,uEAAuE,GACvE,OAAO,iBAAS,eAAe,QAAQ,WAAW,GAAG,IAAI"}

package/node_modules/@ursamu/mushcode/_dist/src/lint/mod.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module
+ * Static analysis for softcode: `lint()` runs built-in rules and returns
+ * `Diagnostic` findings with severity, rule ID, and the offending AST node.
+ *
+ * @example
+ * ```ts
+ * import { parse } from "@ursamu/mushcode/parse";
+ * import { lint }  from "@ursamu/mushcode/lint";
+ *
+ * const ast  = parse("$finger:@pemit %#=[u(me/FN)]");
+ * const diags = lint(ast);
+ * diags.forEach(d => console.log(`[${d.severity}] ${d.rule}: ${d.message}`));
+ * ```
+ */ import type { ASTNode } from "../../parser/mod.js";
+/** Severity level of a lint diagnostic. */ export type Severity = "error" | "warning" | "info";
+/** A single lint finding produced by a rule. */ export interface Diagnostic {
+  /** Identifier for the rule that produced this diagnostic. */ rule: string;
+  /** How serious the finding is. */ severity: Severity;
+  /** Human-readable description of the issue. */ message: string;
+  /** The AST node most closely associated with the issue. */ node: ASTNode;
+}
+/** Options passed to the {@link lint} function. */ export interface LintOptions {
+  /** Whitelist of rule IDs to run.  Omit to run all rules. */ rules?: string[];
+}
+/** All built-in rule IDs.  Pass a subset to `LintOptions.rules` to enable only those rules. */ export declare const RULES: readonly ["missing-wildcard", "iter-var-outside-iter", "arg-count", "register-before-set"];
+/** Union type of every known rule ID string. */ export type RuleId = (typeof RULES)[number];
+/**
+ * Run static analysis on an AST and return an array of diagnostics.
+ *
+ * Rules are applied at every DollarPattern/ListenPattern/FunctionCall/… node
+ * anywhere in the tree, so this works correctly on CommandList roots too.
+ *
+ * @example
+ * const diags = lint(parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]"));
+ * diags.forEach(d => console.log(`[${d.severity}] ${d.rule}: ${d.message}`));
+ */ export declare function lint(root: ASTNode, opts?: LintOptions): Diagnostic[];
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/lint/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../../src/lint/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;CAcC,GACD,cAAc,OAAO,8BAA6C;AASlE,yCAAyC,GACzC,YAAY,WAAW,UAAU,YAAY;AAE7C,8CAA8C,GAC9C,iBAAiB;EACf,2DAA2D,GAC3D,MAAU,MAAM;EAChB,gCAAgC,GAChC,UAAU;EACV,6CAA6C,GAC7C,SAAU,MAAM;EAChB,yDAAyD,GACzD,MAAU;;AAGZ,iDAAiD,GACjD,iBAAiB;EACf,0DAA0D,GAC1D,QAAQ,MAAM;;AAKhB,6FAA6F,GAC7F,OAAO,cAAM,iBACX,oBACA,yBACA,aACA,uBACS;AAEX,8CAA8C,GAC9C,YAAY,iBAAiB,OAAO,MAAM;AAI1C;;;;;;;;;CASC,GACD,OAAO,iBAAS,KAAK,MAAM,OAAO,EAAE,OAAO,WAAW,GAAG"}

package/node_modules/@ursamu/mushcode/_dist/src/print/mod.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @module
+ * Converts an AST back to a canonical softcode string via `print()`.
+ * Supports compact (semicolon-separated) and pretty (newline-separated) modes.
+ *
+ * @example
+ * ```ts
+ * import { parse } from "@ursamu/mushcode/parse";
+ * import { print } from "@ursamu/mushcode/print";
+ *
+ * const ast = parse("@pemit %#=Hello;@pemit %#=World");
+ * console.log(print(ast, { mode: "pretty" }));
+ * // @pemit %#=Hello
+ * // @pemit %#=World
+ * ```
+ */ export type { PrintMode, PrintOptions } from "./printer.js";
+export { print } from "./printer.js";
+//# sourceMappingURL=mod.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/print/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../../src/print/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,cAAc,SAAS,EAAE,YAAY,uBAAuB;AAC5D,SAAS,KAAK,uBAA8C"}

package/node_modules/@ursamu/mushcode/_dist/src/print/printer.d.ts

@@ -0,0 +1,15 @@
+import type { ASTNode } from "../../parser/mod.js";
+/** Controls how `CommandList` separators are rendered in the output. */ export type PrintMode = "compact" | "pretty";
+/** Options for the {@link print} function. */ export interface PrintOptions {
+  /** "compact" (default): CommandList joined by ";".
+   *  "pretty": CommandList joined by ";\n". */ mode?: PrintMode;
+}
+/**
+ * Convert an AST node back to a canonical softcode string.
+ *
+ * The output is semantically equivalent to the original source but whitespace
+ * may be normalised (e.g. `@pemit%#=x` becomes `@pemit %#=x`).
+ * Lock-expression nodes (LockOr, LockAnd, …) produced by the "LockExpr" start
+ * rule are printed via the lock printer.
+ */ export declare function print(node: ASTNode, opts?: PrintOptions): string;
+//# sourceMappingURL=printer.d.ts.map

package/node_modules/@ursamu/mushcode/_dist/src/print/printer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printer.d.ts","sources":["../../../src/print/printer.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,8BAA8B;AAKnD,sEAAsE,GACtE,YAAY,YAAY,YAAY;AAEpC,4CAA4C,GAC5C,iBAAiB;EACf;6CAC2C,GAC3C,OAAO;;AAKT;;;;;;;CAOC,GACD,OAAO,iBAAS,MAAM,MAAM,OAAO,EAAE,OAAO,YAAY,GAAG,MAAM"}

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

@@ -0,0 +1,19 @@
+/**
+ * @module
+ * Depth-first AST traversal and tree transformation utilities:
+ * `walk()`, `transform()`, `findAll()`, `findFirst()`, `findFirstOrNull()`.
+ *
+ * @example
+ * ```ts
+ * import { parse }   from "@ursamu/mushcode/parse";
+ * import { findAll } from "@ursamu/mushcode/traverse";
+ *
+ * const ast = parse("[add(1,[mul(2,3)])]");
+ * const calls = findAll(ast, "FunctionCall");
+ * console.log(calls.map(n => n.name)); // ["add", "mul"]
+ * ```
+ */ export type { Visitor } from "./walk.js";
+export { walk, findAll, findFirst, findFirstOrNull } from "./walk.js";
+export type { Transformer } from "./transform.js";
+export { transform } from "./transform.js";
+//# sourceMappingURL=mod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../../../src/traverse/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;CAcC,GACD,cAAc,OAAO,oBAAwD;AAC7E,SAAS,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,oBAA2B;AAC7E,cAAc,WAAW,yBAAyD;AAClF,SAAS,SAAS,yBAAgE"}