@rhost/testkit 1.5.1 → 1.5.3

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

@@ -0,0 +1,152 @@
+# Lint
+
+```typescript
+import { lint, RULES } from "jsr:@ursamu/mushcode/lint";
+import type { Diagnostic, Severity, LintOptions, RuleId } from "jsr:@ursamu/mushcode/lint";
+```
+
+## `lint(root, opts?)`
+
+Run static analysis on an AST and return an array of diagnostics. All four
+built-in rules run by default.
+
+```typescript
+function lint(root: ASTNode, opts?: LintOptions): Diagnostic[]
+```
+
+```typescript
+import { parse } from "jsr:@ursamu/mushcode/parse";
+import { lint }  from "jsr:@ursamu/mushcode/lint";
+
+const ast   = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+const diags = lint(ast);
+diags.forEach(d => console.log(`[${d.severity}] ${d.rule}: ${d.message}`));
+```
+
+## `LintOptions`
+
+```typescript
+interface LintOptions {
+  rules?: string[]; // subset of RULES to enable; omit to run all
+}
+```
+
+Run only specific rules:
+
+```typescript
+const diags = lint(ast, { rules: ["missing-wildcard", "arg-count"] });
+```
+
+## `RULES`
+
+Tuple of every built-in rule ID:
+
+```typescript
+const RULES = [
+  "missing-wildcard",
+  "iter-var-outside-iter",
+  "arg-count",
+  "register-before-set",
+] as const;
+
+type RuleId = (typeof RULES)[number];
+```
+
+## `Diagnostic`
+
+```typescript
+interface Diagnostic {
+  rule:     string;   // rule ID that produced this diagnostic
+  severity: Severity; // "error" | "warning" | "info"
+  message:  string;
+  node:     ASTNode;  // AST node most closely associated with the issue
+}
+
+type Severity = "error" | "warning" | "info";
+```
+
+The `node` field can be used with its `loc` property to report source positions:
+
+```typescript
+diags.forEach(d => {
+  const loc = d.node.loc?.start;
+  const pos = loc ? ` (line ${loc.line}, col ${loc.column})` : "";
+  console.error(`[${d.severity}] ${d.rule}${pos}: ${d.message}`);
+});
+```
+
+## Built-in rules
+
+### `missing-wildcard`
+
+A `DollarPattern` or `ListenPattern` has no wildcard (`*` or `?`) segment in
+its pattern. This usually means the trigger will only fire on an exact string
+match with no arguments, which is rarely intentional.
+
+```typescript
+// triggers the rule — "$finger" matches only the literal string "finger"
+lint(parse("$finger:@pemit %#=ok"));
+
+// clean — "$finger *" accepts one wildcard argument
+lint(parse("$finger *:@pemit %#=ok"));
+```
+
+### `iter-var-outside-iter`
+
+`##` (iter item) or `#@` (iter index) is used outside of an `iter()` function
+call. These special variables are only defined inside an iteration body; using
+them elsewhere always produces an empty string.
+
+```typescript
+// triggers the rule — ## used at top level
+lint(parse("@pemit %#=##"));
+
+// clean — ## inside iter body
+lint(parse("[iter(a b c,##)]"));
+```
+
+### `arg-count`
+
+A built-in function is called with fewer arguments than its `minArgs` or more
+than its `maxArgs`. The rule checks against known function arities for all
+functions registered in the standard library.
+
+```typescript
+// triggers the rule — add() requires at least 2 arguments
+lint(parse("[add(1)]"));
+
+// triggers the rule — sub() takes exactly 2 arguments
+lint(parse("[sub(1,2,3)]"));
+```
+
+### `register-before-set`
+
+A named register (`%qX` or `r(X)`) is read before `setq(X, …)` has been called
+anywhere in the same expression tree. This does not track runtime flow, only
+whether any `setq` for that register name appears anywhere in the tree.
+
+```typescript
+// triggers the rule — %q0 read before any setq(0, …)
+lint(parse("[r(0)] [setq(0,hello)]"));
+
+// clean — setq before r
+lint(parse("[setq(0,hello)][r(0)]"));
+```
+
+## Example: format diagnostics as editor annotations
+
+```typescript
+import { parse }                from "jsr:@ursamu/mushcode/parse";
+import { lint }                 from "jsr:@ursamu/mushcode/lint";
+import type { Diagnostic }      from "jsr:@ursamu/mushcode/lint";
+
+function annotate(src: string): { line: number; col: number; message: string }[] {
+  const ast   = parse(src);
+  const diags = lint(ast);
+  return diags.map((d: Diagnostic) => ({
+    line:    d.node.loc?.start.line    ?? 1,
+    col:     d.node.loc?.start.column  ?? 1,
+    message: `[${d.rule}] ${d.message}`,
+  }));
+}
+```

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

@@ -0,0 +1,196 @@
+# Parser
+
+```typescript
+import { parse, ParseError } from "jsr:@ursamu/mushcode/parse";
+import type { ASTNode, NodeType, SourceLocation, StartRule } from "jsr:@ursamu/mushcode/parse";
+```
+
+## `parse(text, startRule?)`
+
+Parse a raw softcode string and return its AST root node.
+
+```typescript
+function parse(text: string, startRule?: StartRule): ASTNode
+```
+
+| Parameter   | Type        | Default     | Description                               |
+|-------------|-------------|-------------|-------------------------------------------|
+| `text`      | `string`    | —           | Softcode source to parse                  |
+| `startRule` | `StartRule` | `"Start"`   | Grammar entry point (see below)           |
+
+Throws `ParseError` on syntax errors.
+
+### Start rules
+
+- `"Start"` — normal softcode: commands, function calls, substitutions, patterns
+- `"LockExpr"` — lock expression string, e.g. `flag^WIZARD|attr^STAFF:1`
+
+```typescript
+// Normal softcode
+const ast = parse("$+finger *:@pemit %#=[u(me/FN_FINGER,%0)]");
+
+// Lock expression
+const lock = parse("flag^WIZARD|!flag^GUEST", "LockExpr");
+```
+
+## `ParseError`
+
+Thrown when the parser encounters invalid input.
+
+```typescript
+class ParseError extends Error {
+  readonly location?: { line: number; column: number; offset: number };
+}
+```
+
+```typescript
+try {
+  parse("[unclosed(");
+} catch (e) {
+  if (e instanceof ParseError) {
+    console.error(`Syntax error at line ${e.location?.line}: ${e.message}`);
+  }
+}
+```
+
+## Types
+
+### `ASTNode`
+
+Every node in the tree conforms to this type:
+
+```typescript
+type ASTNode = {
+  type: string;         // node type discriminant
+  loc?: SourceLocation; // source span (always present unless disabled)
+  [key: string]: any;   // node-specific fields
+};
+```
+
+Node-specific fields are accessed by checking `node.type` first:
+
+```typescript
+if (ast.type === "FunctionCall") {
+  console.log(ast.name);              // string
+  console.log((ast.args as ASTNode[]).length);
+}
+if (ast.type === "Literal") {
+  console.log(ast.value as string);
+}
+```
+
+### `SourceLocation`
+
+```typescript
+interface SourceLocation {
+  start: SourcePosition;
+  end:   SourcePosition;
+}
+
+interface SourcePosition {
+  offset: number; // byte offset from start of input (0-based)
+  line:   number; // 1-based line number
+  column: number; // 1-based column number
+}
+```
+
+```typescript
+const ast = parse("add(1,2)");
+// ast.loc.start → { offset: 0, line: 1, column: 1 }
+// ast.loc.end   → { offset: 8, line: 1, column: 9 }
+```
+
+### `NodeType`
+
+Union of every type string the parser can produce:
+
+```typescript
+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";
+```
+
+## Node reference
+
+### Expression nodes
+
+| Type           | Key fields                              | Description                            |
+|----------------|-----------------------------------------|----------------------------------------|
+| `Literal`      | `value: string`                         | Plain text segment                     |
+| `Escape`       | `char: string`                          | Backslash-escaped character            |
+| `Substitution` | `code: string`                          | `%X` substitution (code = `"#"`, `"0"`, `"qA"`, …) |
+| `SpecialVar`   | `code: string`                          | `##` (iter item) or `#@` (iter index)  |
+| `TagRef`       | `name: string`                          | `#tagname` reference                   |
+| `EvalBlock`    | `parts: ASTNode[]`                      | `[…]` evaluated block                  |
+| `BracedString` | `parts: ASTNode[]`                      | `{…}` braced literal                   |
+| `Arg`          | `parts: ASTNode[]`                      | One comma-separated function argument  |
+| `FunctionCall` | `name: string`, `args: ASTNode[]`       | `name(arg1,arg2,…)`                    |
+
+### Command nodes
+
+| Type           | Key fields                                                        | Description              |
+|----------------|-------------------------------------------------------------------|--------------------------|
+| `CommandList`  | `commands: ASTNode[]`                                             | `;`-separated statements |
+| `AtCommand`    | `name: string`, `switches: string[]`, `object?: ASTNode`, `value?: ASTNode` | `@name/sw obj=val` |
+| `AttributeSet` | `attribute: string`, `object: ASTNode`, `value?: ASTNode`        | `&ATTR obj=val`          |
+| `UserCommand`  | `parts: ASTNode[]`                                                | Freeform typed command   |
+
+### Pattern nodes
+
+| Type            | Key fields                              | Description                        |
+|-----------------|-----------------------------------------|------------------------------------|
+| `DollarPattern` | `pattern: ASTNode`, `action: ASTNode`   | `$pattern:action` trigger          |
+| `ListenPattern` | `pattern: ASTNode`, `action: ASTNode`   | `^pattern:action` listen trigger   |
+| `Pattern`       | `parts: ASTNode[]`                      | Pattern body segments              |
+| `PatternAlts`   | `patterns: ASTNode[]`                   | `;`-separated pattern alternatives |
+| `Wildcard`      | `wildcard: string`                      | `"*"` or `"?"`                     |
+
+### Lock nodes (LockExpr start rule)
+
+| Type              | Key fields                              |
+|-------------------|-----------------------------------------|
+| `LockOr`          | `left: ASTNode`, `right: ASTNode`       |
+| `LockAnd`         | `left: ASTNode`, `right: ASTNode`       |
+| `LockNot`         | `operand: ASTNode`                      |
+| `LockMe`          | _(no extra fields)_                     |
+| `LockDbref`       | `dbref: string`                         |
+| `LockFlagCheck`   | `flag: string`                          |
+| `LockTypeCheck`   | `objtype: string`                       |
+| `LockAttrCheck`   | `attr: string`, `value: string`         |
+| `LockPlayerName`  | `name: string`                          |
+
+## Examples
+
+### Collecting all substitution codes in a softcode string
+
+```typescript
+import { parse }   from "jsr:@ursamu/mushcode/parse";
+import { findAll } from "jsr:@ursamu/mushcode/traverse";
+
+const ast  = parse("@pemit %#=Hello %N, you have %0 coins.");
+const subs = findAll(ast, "Substitution");
+console.log(subs.map(n => n.code)); // ["#", "N", "0"]
+```
+
+### Checking for parse errors with location info
+
+```typescript
+import { parse, ParseError } from "jsr:@ursamu/mushcode/parse";
+
+function safeParse(src: string) {
+  try {
+    return { ok: true, ast: parse(src) };
+  } catch (e) {
+    if (e instanceof ParseError) {
+      return { ok: false, error: e.message, line: e.location?.line };
+    }
+    throw e;
+  }
+}
+```

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

@@ -0,0 +1,84 @@
+# Print
+
+```typescript
+import { print } from "jsr:@ursamu/mushcode/print";
+import type { PrintOptions, PrintMode } from "jsr:@ursamu/mushcode/print";
+```
+
+## `print(node, opts?)`
+
+Convert an AST node back to a canonical softcode string.
+
+```typescript
+function print(node: ASTNode, opts?: PrintOptions): string
+```
+
+The output is semantically equivalent to the original source. Whitespace around
+`@command` syntax may be normalised (e.g. `@pemit%#=x` becomes `@pemit %#=x`).
+
+Lock-expression nodes (`LockOr`, `LockAnd`, etc.) produced by the `"LockExpr"`
+start rule are handled automatically.
+
+## `PrintOptions`
+
+```typescript
+interface PrintOptions {
+  mode?: PrintMode; // default: "compact"
+}
+
+type PrintMode = "compact" | "pretty";
+```
+
+| Mode        | `CommandList` separator |
+|-------------|-------------------------|
+| `"compact"` | `;`                     |
+| `"pretty"`  | `;\n`                   |
+
+## Examples
+
+### Round-trip a softcode string
+
+```typescript
+import { parse } from "jsr:@ursamu/mushcode/parse";
+import { print } from "jsr:@ursamu/mushcode/print";
+
+const src = "$+say *:@pemit/noeval %#=You say: %0";
+const ast = parse(src);
+console.log(print(ast)); // "$+say *:@pemit/noeval %#=You say: %0"
+```
+
+### Pretty-print a command list
+
+```typescript
+import { parse } from "jsr:@ursamu/mushcode/parse";
+import { print } from "jsr:@ursamu/mushcode/print";
+
+const ast = parse("@pemit %#=Line one;@pemit %#=Line two;@pemit %#=Line three");
+console.log(print(ast, { mode: "pretty" }));
+// @pemit %#=Line one
+// @pemit %#=Line two
+// @pemit %#=Line three
+```
+
+### Print a transformed tree
+
+```typescript
+import { parse }     from "jsr:@ursamu/mushcode/parse";
+import { transform } from "jsr:@ursamu/mushcode/traverse";
+import { print }     from "jsr:@ursamu/mushcode/print";
+
+// Strip all TagRef nodes before printing
+const ast = parse("@pemit %#=[get(#room/DESC)]");
+const out = transform(ast, (n) => n.type === "TagRef" ? null : undefined);
+console.log(print(out));
+```
+
+### Print a lock expression
+
+```typescript
+import { parse } from "jsr:@ursamu/mushcode/parse";
+import { print } from "jsr:@ursamu/mushcode/print";
+
+const lock = parse("flag^WIZARD|!flag^GUEST", "LockExpr");
+console.log(print(lock)); // "flag^WIZARD|!flag^GUEST"
+```