@rhost/testkit 0.1.1 → 1.3.2

package/dist/validator/checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.js","sourceRoot":"","sources":["../../src/validator/checker.ts"],"names":[],"mappings":"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"}

package/dist/validator/clobber.d.ts

@@ -0,0 +1,7 @@
+import { ASTNode, Diagnostic } from './types';
+/**
+ * Walk the AST and emit W006 warnings for every `setq()` call that appears
+ * inside a loop-body argument without an intervening `localize()`.
+ */
+export declare function registerClobberCheck(nodes: ASTNode[]): Diagnostic[];
+//# sourceMappingURL=clobber.d.ts.map

package/dist/validator/clobber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clobber.d.ts","sourceRoot":"","sources":["../../src/validator/clobber.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAoB,MAAM,SAAS,CAAC;AAsBhE;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,CAInE"}

package/dist/validator/clobber.js

@@ -0,0 +1,102 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Register clobber / re-entrancy analyzer
+//
+// Detects `setq()` calls inside loop-body arguments (iter, parse, filter,
+// map, fold, step, munge, filterfun).  Because MUSH registers (%q0–%q9) are
+// scoped per queue entry, concurrent or nested invocations of the same
+// attribute can silently overwrite each other's register values.
+//
+// Safe escape hatch: wrapping the body in `localize()` creates a fresh
+// register scope, so setq() inside localize() is not flagged.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerClobberCheck = registerClobberCheck;
+// Functions whose body argument is evaluated once per list element.
+// Value is the index of the first "body" argument (0-based).
+// All arguments at index >= bodyArgIndex are treated as body.
+const LOOP_FUNCTIONS = new Map([
+    ['iter', 1], // iter(list, BODY, ...)
+    ['parse', 1], // parse(list, BODY, ...)
+    ['filter', 0], // filter(BODY/attr, list, ...)
+    ['filterfun', 0], // filterfun(BODY/attr, list, ...)
+    ['map', 0], // map(BODY/attr, list, ...)
+    ['fold', 0], // fold(BODY/attr, base, list, ...)
+    ['step', 0], // step(BODY/attr, list, ...)
+    ['munge', 0], // munge(BODY/attr, list, ...)
+    ['matchall', 1], // matchall(list, pattern, ...) — pattern is text, not code
+    ['graball', 1], // graball(list, pattern, ...)
+    ['sortby', 0], // sortby(BODY/attr, list, ...)
+]);
+// Functions that create a new register scope — safe for setq()
+const SCOPE_WRAPPERS = new Set(['localize']);
+/**
+ * Walk the AST and emit W006 warnings for every `setq()` call that appears
+ * inside a loop-body argument without an intervening `localize()`.
+ */
+function registerClobberCheck(nodes) {
+    const diagnostics = [];
+    walkNodes(nodes, false, diagnostics);
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// Internal walkers
+// ---------------------------------------------------------------------------
+function walkNodes(nodes, inLoop, out) {
+    for (const node of nodes) {
+        walkNode(node, inLoop, out);
+    }
+}
+function walkNode(node, inLoop, out) {
+    switch (node.type) {
+        case 'BracketEval':
+            walkNodes(node.nodes, inLoop, out);
+            break;
+        case 'FunctionCall':
+            walkFunctionCall(node, inLoop, out);
+            break;
+        // RawText / Substitution — nothing to check
+        default:
+            break;
+    }
+}
+function walkFunctionCall(node, inLoop, out) {
+    const key = node.name.toLowerCase();
+    // localize() creates a new register scope — safe to setq() inside
+    if (SCOPE_WRAPPERS.has(key)) {
+        for (const arg of node.args) {
+            walkNodes(arg, false, out); // reset inLoop to false
+        }
+        return;
+    }
+    // setq() inside a loop body is the hazard
+    if (inLoop && key === 'setq') {
+        out.push({
+            severity: 'warning',
+            code: 'W006',
+            message: `'setq' inside a loop body risks register clobber on re-entrant calls — ` +
+                `wrap the body with localize() to create a safe register scope`,
+            offset: node.nameOffset,
+            length: node.name.length,
+        });
+        // Still recurse so nested loops / deeper setqs are also caught
+        for (const arg of node.args) {
+            walkNodes(arg, inLoop, out);
+        }
+        return;
+    }
+    const bodyArgIndex = LOOP_FUNCTIONS.get(key);
+    if (bodyArgIndex !== undefined) {
+        for (let i = 0; i < node.args.length; i++) {
+            // Arguments before the body start index are data (list, base value, etc.) — not loop body
+            const isBodyArg = i >= bodyArgIndex;
+            walkNodes(node.args[i], isBodyArg, out);
+        }
+        return;
+    }
+    // Regular function — propagate current inLoop state
+    for (const arg of node.args) {
+        walkNodes(arg, inLoop, out);
+    }
+}
+//# sourceMappingURL=clobber.js.map

package/dist/validator/clobber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clobber.js","sourceRoot":"","sources":["../../src/validator/clobber.ts"],"names":[],"mappings":"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"}

package/dist/validator/compat.d.ts

@@ -0,0 +1,19 @@
+import { ASTNode } from './types';
+import { Platform } from './builtins';
+export interface CompatibilityEntry {
+    name: string;
+    /** Platforms that support this function. */
+    platforms: Platform[];
+}
+export interface CompatibilityReport {
+    /** Functions that are not available on all platforms. */
+    restricted: CompatibilityEntry[];
+    /** true if every known function in the expression is universally portable. */
+    portable: boolean;
+}
+/**
+ * Walk a parsed AST and collect any platform-restricted function calls.
+ * Called internally by `compatibilityReport` in the validator index.
+ */
+export declare function compatibilityCheck(nodes: ASTNode[]): CompatibilityReport;
+//# sourceMappingURL=compat.d.ts.map

package/dist/validator/compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../../src/validator/compat.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAoB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAqB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,SAAS,EAAE,QAAQ,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAChC,yDAAyD;IACzD,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,mBAAmB,CAYxE"}

package/dist/validator/compat.js

@@ -0,0 +1,58 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Dialect compatibility report
+//
+// Walks the AST and reports which functions are restricted to specific
+// platforms (Rhost-only, Penn+Rhost, etc.) vs. universally available.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compatibilityCheck = compatibilityCheck;
+const builtins_1 = require("./builtins");
+/**
+ * Walk a parsed AST and collect any platform-restricted function calls.
+ * Called internally by `compatibilityReport` in the validator index.
+ */
+function compatibilityCheck(nodes) {
+    const seen = new Map();
+    walkNodes(nodes, seen);
+    const restricted = Array.from(seen.entries()).map(([name, platforms]) => ({ name, platforms }));
+    return {
+        restricted,
+        portable: restricted.length === 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal walkers
+// ---------------------------------------------------------------------------
+function walkNodes(nodes, seen) {
+    for (const node of nodes) {
+        walkNode(node, seen);
+    }
+}
+function walkNode(node, seen) {
+    switch (node.type) {
+        case 'FunctionCall':
+            checkFunction(node, seen);
+            break;
+        case 'BracketEval':
+            walkNodes(node.nodes, seen);
+            break;
+        default:
+            break;
+    }
+}
+function checkFunction(node, seen) {
+    const key = node.name.toLowerCase();
+    const sig = builtins_1.BUILTIN_FUNCTIONS.get(key);
+    if (sig?.platforms && sig.platforms.length > 0) {
+        // Deduplicate — only record each restricted function once
+        if (!seen.has(key)) {
+            seen.set(key, sig.platforms);
+        }
+    }
+    // Recurse into arguments
+    for (const arg of node.args) {
+        walkNodes(arg, seen);
+    }
+}
+//# sourceMappingURL=compat.js.map

package/dist/validator/compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.js","sourceRoot":"","sources":["../../src/validator/compat.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,+BAA+B;AAC/B,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,8EAA8E;;AAsB9E,gDAYC;AA/BD,yCAAyD;AAezD;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,KAAgB;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC3C,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAEvB,MAAM,UAAU,GAAyB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CACnE,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAC/C,CAAC;IAEF,OAAO;QACH,UAAU;QACV,QAAQ,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC;KACpC,CAAC;AACN,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,SAAS,SAAS,CAAC,KAAgB,EAAE,IAA6B;IAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,IAAa,EAAE,IAA6B;IAC1D,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,cAAc;YACf,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1B,MAAM;QACV,KAAK,aAAa;YACd,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC5B,MAAM;QACV;YACI,MAAM;IACd,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,IAAsB,EAAE,IAA6B;IACxE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,4BAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEvC,IAAI,GAAG,EAAE,SAAS,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,0DAA0D;QAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QACjC,CAAC;IACL,CAAC;IAED,yBAAyB;IACzB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;AACL,CAAC"}

package/dist/validator/formatter.d.ts

@@ -0,0 +1,21 @@
+export interface FormatOptions {
+    /** Add newlines + indentation for human readability. Default: false. */
+    pretty?: boolean;
+    /** Lowercase all function names. Default: false. */
+    lowercase?: boolean;
+}
+export interface FormatResult {
+    formatted: string;
+    changed: boolean;
+}
+/**
+ * Format a MUSHcode expression.
+ *
+ * Compact mode (default): strips extra whitespace around `(`, `,`, `)` while
+ * preserving whitespace inside argument text.
+ *
+ * Pretty mode: additionally adds newlines + indentation at each nesting level
+ * for human readability. Not suitable for direct upload to a MUSH server.
+ */
+export declare function format(expr: string, options?: FormatOptions): FormatResult;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/validator/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/validator/formatter.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAO9E"}

package/dist/validator/formatter.js

@@ -0,0 +1,120 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Softcode Formatter — serialize an AST back to a normalized string
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.format = format;
+const tokenizer_1 = require("./tokenizer");
+const parser_1 = require("./parser");
+/**
+ * Format a MUSHcode expression.
+ *
+ * Compact mode (default): strips extra whitespace around `(`, `,`, `)` while
+ * preserving whitespace inside argument text.
+ *
+ * Pretty mode: additionally adds newlines + indentation at each nesting level
+ * for human readability. Not suitable for direct upload to a MUSH server.
+ */
+function format(expr, options = {}) {
+    const tokens = (0, tokenizer_1.tokenize)(expr);
+    const { nodes } = (0, parser_1.parse)(tokens);
+    const serializer = new Serializer(options);
+    const formatted = serializer.serializeNodes(nodes, 0);
+    return { formatted, changed: formatted !== expr };
+}
+// ---------------------------------------------------------------------------
+// Serializer
+// ---------------------------------------------------------------------------
+class Serializer {
+    constructor(opts) {
+        this.opts = opts;
+    }
+    serializeNodes(nodes, depth) {
+        return nodes.map(n => this.serializeNode(n, depth)).join('');
+    }
+    serializeNode(node, depth) {
+        switch (node.type) {
+            case 'FunctionCall': return this.serializeFunctionCall(node, depth);
+            case 'BracketEval': return this.serializeBracketEval(node, depth);
+            case 'Substitution': return node.raw;
+            case 'RawText': return node.value;
+        }
+    }
+    serializeFunctionCall(node, depth) {
+        const name = this.opts.lowercase ? node.name.toLowerCase() : node.name;
+        if (node.args.length === 0) {
+            return `${name}()`;
+        }
+        // Trim leading/trailing RawText whitespace from each arg
+        const trimmedArgs = node.args.map(arg => trimArgWhitespace(arg));
+        const pretty = this.opts.pretty;
+        // Pretty mode: wrap if any arg contains a function call
+        if (pretty && hasNestedCall(trimmedArgs)) {
+            const indent = '  '.repeat(depth + 1);
+            const closingIndent = '  '.repeat(depth);
+            const serializedArgs = trimmedArgs.map(arg => indent + this.serializeNodes(arg, depth + 1));
+            return `${name}(\n${serializedArgs.join(',\n')}\n${closingIndent})`;
+        }
+        const serializedArgs = trimmedArgs.map(arg => this.serializeNodes(arg, depth + 1));
+        return `${name}(${serializedArgs.join(',')})`;
+    }
+    serializeBracketEval(node, depth) {
+        return `[${this.serializeNodes(node.nodes, depth)}]`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Trim leading and trailing RawText-whitespace-only nodes from an arg list. */
+function trimArgWhitespace(arg) {
+    if (arg.length === 0)
+        return arg;
+    let start = 0;
+    let end = arg.length - 1;
+    // Trim leading whitespace-only RawText nodes
+    while (start <= end) {
+        const node = arg[start];
+        if (node.type === 'RawText' && node.value.trim() === '') {
+            start++;
+        }
+        else {
+            break;
+        }
+    }
+    // Trim trailing whitespace-only RawText nodes
+    while (end >= start) {
+        const node = arg[end];
+        if (node.type === 'RawText' && node.value.trim() === '') {
+            end--;
+        }
+        else {
+            break;
+        }
+    }
+    if (start > end)
+        return [];
+    const trimmed = arg.slice(start, end + 1);
+    // Also trim leading whitespace from the value of the first RawText node
+    // (handles cases like arg starting with a non-whitespace-only RawText that begins with spaces)
+    if (trimmed.length > 0 && trimmed[0].type === 'RawText') {
+        const first = trimmed[0];
+        const trimmedValue = first.value.trimStart();
+        if (trimmedValue !== first.value) {
+            trimmed[0] = { ...first, value: trimmedValue };
+        }
+    }
+    // And trailing whitespace from the last RawText node
+    if (trimmed.length > 0 && trimmed[trimmed.length - 1].type === 'RawText') {
+        const last = trimmed[trimmed.length - 1];
+        const trimmedValue = last.value.trimEnd();
+        if (trimmedValue !== last.value) {
+            trimmed[trimmed.length - 1] = { ...last, value: trimmedValue };
+        }
+    }
+    return trimmed;
+}
+/** Returns true if any arg list contains a FunctionCall node (for pretty indentation decisions). */
+function hasNestedCall(args) {
+    return args.some(arg => arg.some(node => node.type === 'FunctionCall' || node.type === 'BracketEval'));
+}
+//# sourceMappingURL=formatter.js.map

package/dist/validator/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/validator/formatter.ts"],"names":[],"mappings":"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"}

package/dist/validator/index.d.ts

@@ -0,0 +1,57 @@
+import { CompatibilityReport } from './compat';
+import { ValidationResult } from './types';
+export { ValidationResult, Diagnostic, Severity } from './types';
+export { FunctionSignature, BUILTIN_FUNCTIONS, Platform } from './builtins';
+export { CompatibilityReport, CompatibilityEntry } from './compat';
+/**
+ * Validate a RhostMUSH softcode expression without a server connection.
+ *
+ * The validator runs three stages:
+ *  1. **Tokenizer** — converts the expression to a flat token stream
+ *  2. **Parser** — builds an AST; detects structural errors (unbalanced parens/brackets)
+ *  3. **Semantic checker** — validates function names and argument counts
+ *
+ * `valid` is `true` unless at least one diagnostic has `severity: 'error'`.
+ * Warnings do not affect validity.
+ *
+ * @example
+ *   import { validate } from '@rhost/testkit/validator';
+ *
+ *   const result = validate('add(2,3)');
+ *   // { valid: true, diagnostics: [] }
+ *
+ *   const bad = validate('add(2,3');
+ *   // { valid: false, diagnostics: [{ code: 'E001', severity: 'error', ... }] }
+ *
+ * @example Catch wrong arg count
+ *   validate('abs(1,2)');
+ *   // { valid: false, diagnostics: [{ code: 'E007', ... }] }
+ *
+ * @example Unknown function (warning, still valid)
+ *   validate('myfunc(arg)');
+ *   // { valid: true, diagnostics: [{ code: 'W005', severity: 'warning', ... }] }
+ */
+export declare function validate(expr: string): ValidationResult;
+/**
+ * Analyse a softcode expression for cross-platform dialect compatibility.
+ *
+ * Returns a `CompatibilityReport` listing any functions that are not
+ * available on all MUSH platforms (PennMUSH, TinyMUX, RhostMUSH).
+ *
+ * @example
+ *   const report = compatibilityReport('encode64(hello)');
+ *   // report.portable === false
+ *   // report.restricted === [{ name: 'encode64', platforms: ['rhost'] }]
+ */
+export declare function compatibilityReport(expr: string): CompatibilityReport;
+/**
+ * Validate the softcode expression contained in a file.
+ *
+ * The entire file content is treated as a single expression.
+ * For files with multiple expressions (e.g. one per line) consider
+ * reading and validating each line individually.
+ *
+ * @throws If the file cannot be read.
+ */
+export declare function validateFile(filePath: string): ValidationResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/validator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAsB,mBAAmB,EAAsB,MAAM,UAAU,CAAC;AACvF,OAAO,EAAc,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAwBvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAOrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAG/D"}

package/dist/validator/index.js

@@ -0,0 +1,133 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Public API for the RhostMUSH softcode offline validator
+// ---------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_FUNCTIONS = void 0;
+exports.validate = validate;
+exports.compatibilityReport = compatibilityReport;
+exports.validateFile = validateFile;
+const fs = __importStar(require("fs"));
+const tokenizer_1 = require("./tokenizer");
+const parser_1 = require("./parser");
+const checker_1 = require("./checker");
+const clobber_1 = require("./clobber");
+const compat_1 = require("./compat");
+var builtins_1 = require("./builtins");
+Object.defineProperty(exports, "BUILTIN_FUNCTIONS", { enumerable: true, get: function () { return builtins_1.BUILTIN_FUNCTIONS; } });
+/**
+ * Validate a RhostMUSH softcode expression without a server connection.
+ *
+ * The validator runs three stages:
+ *  1. **Tokenizer** — converts the expression to a flat token stream
+ *  2. **Parser** — builds an AST; detects structural errors (unbalanced parens/brackets)
+ *  3. **Semantic checker** — validates function names and argument counts
+ *
+ * `valid` is `true` unless at least one diagnostic has `severity: 'error'`.
+ * Warnings do not affect validity.
+ *
+ * @example
+ *   import { validate } from '@rhost/testkit/validator';
+ *
+ *   const result = validate('add(2,3)');
+ *   // { valid: true, diagnostics: [] }
+ *
+ *   const bad = validate('add(2,3');
+ *   // { valid: false, diagnostics: [{ code: 'E001', severity: 'error', ... }] }
+ *
+ * @example Catch wrong arg count
+ *   validate('abs(1,2)');
+ *   // { valid: false, diagnostics: [{ code: 'E007', ... }] }
+ *
+ * @example Unknown function (warning, still valid)
+ *   validate('myfunc(arg)');
+ *   // { valid: true, diagnostics: [{ code: 'W005', severity: 'warning', ... }] }
+ */
+function validate(expr) {
+    // Empty expression: valid but warn
+    if (expr.trim() === '') {
+        const diagnostics = [
+            {
+                severity: 'warning',
+                code: 'W001',
+                message: 'Expression is empty',
+                offset: 0,
+                length: 0,
+            },
+        ];
+        return { valid: true, diagnostics };
+    }
+    const tokens = (0, tokenizer_1.tokenize)(expr);
+    const { nodes, diagnostics: structural } = (0, parser_1.parse)(tokens);
+    const semantic = (0, checker_1.semanticCheck)(nodes);
+    const clobber = (0, clobber_1.registerClobberCheck)(nodes);
+    const all = [...structural, ...semantic, ...clobber];
+    const valid = !all.some((d) => d.severity === 'error');
+    return { valid, diagnostics: all };
+}
+/**
+ * Analyse a softcode expression for cross-platform dialect compatibility.
+ *
+ * Returns a `CompatibilityReport` listing any functions that are not
+ * available on all MUSH platforms (PennMUSH, TinyMUX, RhostMUSH).
+ *
+ * @example
+ *   const report = compatibilityReport('encode64(hello)');
+ *   // report.portable === false
+ *   // report.restricted === [{ name: 'encode64', platforms: ['rhost'] }]
+ */
+function compatibilityReport(expr) {
+    if (expr.trim() === '') {
+        return { restricted: [], portable: true };
+    }
+    const tokens = (0, tokenizer_1.tokenize)(expr);
+    const { nodes } = (0, parser_1.parse)(tokens);
+    return (0, compat_1.compatibilityCheck)(nodes);
+}
+/**
+ * Validate the softcode expression contained in a file.
+ *
+ * The entire file content is treated as a single expression.
+ * For files with multiple expressions (e.g. one per line) consider
+ * reading and validating each line individually.
+ *
+ * @throws If the file cannot be read.
+ */
+function validateFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return validate(content);
+}
+//# sourceMappingURL=index.js.map

package/dist/validator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0C9E,4BAwBC;AAaD,kDAOC;AAWD,oCAGC;AAlGD,uCAAyB;AACzB,2CAAuC;AACvC,qCAAiC;AACjC,uCAA0C;AAC1C,uCAAiD;AACjD,qCAAuF;AAIvF,uCAA4E;AAAhD,6GAAA,iBAAiB,OAAA;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,QAAQ,CAAC,IAAY;IACnC,mCAAmC;IACnC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACvB,MAAM,WAAW,GAAiB;YAChC;gBACE,QAAQ,EAAE,SAAS;gBACnB,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,qBAAqB;gBAC9B,MAAM,EAAE,CAAC;gBACT,MAAM,EAAE,CAAC;aACV;SACF,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACtC,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,oBAAQ,EAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,IAAA,cAAK,EAAC,MAAM,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAA,uBAAa,EAAC,KAAK,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAA,8BAAoB,EAAC,KAAK,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAEvD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,IAAY;IAC9C,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACvB,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,MAAM,GAAG,IAAA,oBAAQ,EAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,EAAE,KAAK,EAAE,GAAG,IAAA,cAAK,EAAC,MAAM,CAAC,CAAC;IAChC,OAAO,IAAA,2BAAkB,EAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAAC,QAAgB;IAC3C,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC"}

package/dist/validator/parser.d.ts

@@ -0,0 +1,16 @@
+import { Token } from './tokenizer';
+import { ASTNode, Diagnostic } from './types';
+export interface ParseResult {
+    nodes: ASTNode[];
+    /** Structural diagnostics: unclosed parens/brackets, stray ), ], etc. */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Parse a flat token stream into an AST.
+ *
+ * Structural errors (unbalanced parens/brackets) are embedded in `diagnostics`.
+ * The returned `nodes` array always contains the best-effort parse even when
+ * there are errors, enabling downstream semantic checks to still run.
+ */
+export declare function parse(tokens: Token[]): ParseResult;
+//# sourceMappingURL=parser.d.ts.map

package/dist/validator/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/validator/parser.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,OAAO,EAAmB,UAAU,EAAmD,MAAM,SAAS,CAAC;AAEhH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,yEAAyE;IACzE,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AA4RD;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,WAAW,CAIlD"}