@zocomputer/system-api 0.0.0-stage → 0.1.1

package/dist/validation/pattern.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Portable, linear-time regular expressions for System API `pattern` keywords —
+ * a faithful port of `hostagent.system_api.pattern`, so a workspace-published
+ * pattern means the same thing to the Python validator and to this SDK.
+ *
+ * A deliberately small subset is parsed to an AST, then re-emitted in explicit
+ * Rust `regex` syntax (brace hex escapes, `\z` for end-of-text, an explicit
+ * line-terminator class for `.`) and executed with re2js — a finite-automaton
+ * matcher with no backtracking, so `(a+)+b` on a long input finishes at once.
+ * The emitted string is byte-identical to the Python emitter's, and the same
+ * three complexity rules (per-count cap, nested product, expansion cap) run
+ * over the AST before any engine sees it, so a server-accepted pattern is
+ * engine-compilable on both sides.
+ *
+ * Supported: literals; escapes `\n \t \r \f \v`, `\xHH`, `\uHHHH`, and a
+ * backslash before any punctuation; `.` (all but `\n \r
+ 
+`);
+ * classes `[...]`/`[^...]` with ranges (no nesting); groups `(...)`/`(?:...)`;
+ * alternation `|`; quantifiers `* + ?` and `{n} {n,} {n,m}` (optionally lazy);
+ * anchors `^` and `$`. Rejected: `\d \w \s \b`, lookaround, named groups,
+ * backreferences, inline flags, possessive quantifiers, class set operations.
+ */
+import { RE2JS } from "re2js";
+export declare const MAX_PATTERN_LENGTH = 256;
+/** Largest count in `{n}`/`{n,}`/`{n,m}` — the fixed RE2-family limit. */
+export declare const MAX_PATTERN_REPETITION = 1000;
+/** Largest product of counted repetitions along any nesting path (RE2's rule). */
+export declare const MAX_NESTED_REPETITION = 1000;
+/** Work cap on the expanded program size, in re2js `calcSize` units. */
+export declare const MAX_PATTERN_EXPANSION = 250000;
+/** The pattern is outside the portable subset or too complex. */
+export declare class PatternError extends Error {
+    constructor(message: string);
+}
+/** A compiled portable pattern executed by the re2js (RE2) engine. */
+export declare class PortablePattern {
+    readonly source: string;
+    readonly rust: string;
+    private readonly compiled;
+    constructor(source: string, rust: string, compiled: RE2JS);
+    /**
+     * True when the pattern matches anywhere in `text` (unanchored, like Python
+     * `re.search` / rust-regex `is_match` and JavaScript `RegExp.prototype.test`).
+     */
+    search(text: string): boolean;
+}
+/**
+ * Parse `pattern` against the portable subset and compile it for the
+ * linear-time engine; throws `PatternError` (never echoing input strings).
+ */
+export declare function compilePattern(pattern: string): PortablePattern;
+/** The explicit Rust-syntax form of a portable pattern (tests and export). */
+export declare function toRustSyntax(pattern: string): string;
+/** The shared work metric of a portable pattern (tests and parity checks). */
+export declare function expansionSize(pattern: string): number;

package/dist/validation/pattern.js

@@ -0,0 +1,382 @@
+/**
+ * Portable, linear-time regular expressions for System API `pattern` keywords —
+ * a faithful port of `hostagent.system_api.pattern`, so a workspace-published
+ * pattern means the same thing to the Python validator and to this SDK.
+ *
+ * A deliberately small subset is parsed to an AST, then re-emitted in explicit
+ * Rust `regex` syntax (brace hex escapes, `\z` for end-of-text, an explicit
+ * line-terminator class for `.`) and executed with re2js — a finite-automaton
+ * matcher with no backtracking, so `(a+)+b` on a long input finishes at once.
+ * The emitted string is byte-identical to the Python emitter's, and the same
+ * three complexity rules (per-count cap, nested product, expansion cap) run
+ * over the AST before any engine sees it, so a server-accepted pattern is
+ * engine-compilable on both sides.
+ *
+ * Supported: literals; escapes `\n \t \r \f \v`, `\xHH`, `\uHHHH`, and a
+ * backslash before any punctuation; `.` (all but `\n \r
+ 
+`);
+ * classes `[...]`/`[^...]` with ranges (no nesting); groups `(...)`/`(?:...)`;
+ * alternation `|`; quantifiers `* + ?` and `{n} {n,} {n,m}` (optionally lazy);
+ * anchors `^` and `$`. Rejected: `\d \w \s \b`, lookaround, named groups,
+ * backreferences, inline flags, possessive quantifiers, class set operations.
+ */
+import { RE2JS } from "re2js";
+export const MAX_PATTERN_LENGTH = 256;
+/** Largest count in `{n}`/`{n,}`/`{n,m}` — the fixed RE2-family limit. */
+export const MAX_PATTERN_REPETITION = 1000;
+/** Largest product of counted repetitions along any nesting path (RE2's rule). */
+export const MAX_NESTED_REPETITION = 1000;
+/** Work cap on the expanded program size, in re2js `calcSize` units. */
+export const MAX_PATTERN_EXPANSION = 250_000;
+const PUNCT_ESCAPES = new Set("\\/.*+?()[]{}|^$-");
+const SIMPLE_ESCAPES = {
+    n: "\n",
+    t: "\t",
+    r: "\r",
+    f: "\f",
+    v: "\v",
+};
+const HEX = new Set("0123456789abcdefABCDEF");
+const CLASS_SET_OPS = ["--", "&&", "~~", "||"];
+const LINE_TERMINATORS = [
+    [0x0a, 0x0a],
+    [0x0d, 0x0d],
+    [0x2028, 0x2029],
+];
+/** The pattern is outside the portable subset or too complex. */
+export class PatternError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PatternError";
+    }
+}
+// --- parser ------------------------------------------------------------------
+class Parser {
+    /** Code points, so `pos` advances one code point at a time (Python parity). */
+    chars;
+    pos = 0;
+    constructor(pattern) {
+        this.chars = Array.from(pattern);
+    }
+    fail(message) {
+        throw new PatternError(`unsupported pattern: ${message}`);
+    }
+    peek(offset = 0) {
+        const index = this.pos + offset;
+        return index < this.chars.length ? this.chars[index] : "";
+    }
+    startsWith(prefix) {
+        return (this.chars.slice(this.pos, this.pos + prefix.length).join("") === prefix);
+    }
+    parse() {
+        const node = this.parseAlt();
+        if (this.pos !== this.chars.length)
+            this.fail("unbalanced ')'");
+        return node;
+    }
+    parseAlt() {
+        const branches = [this.parseSeq()];
+        while (this.peek() === "|") {
+            this.pos += 1;
+            branches.push(this.parseSeq());
+        }
+        return branches.length === 1 ? branches[0] : { kind: "alt", branches };
+    }
+    parseSeq() {
+        const items = [];
+        while (this.pos < this.chars.length && !"|)".includes(this.peek())) {
+            items.push(this.parseQuantifier(this.parseAtom()));
+        }
+        return items.length === 1 ? items[0] : { kind: "seq", items };
+    }
+    parseAtom() {
+        const c = this.peek();
+        if (c === "(") {
+            if (this.startsWith("(?:"))
+                this.pos += 3;
+            else if (this.startsWith("(?"))
+                this.fail("unsupported group syntax");
+            else
+                this.pos += 1;
+            const inner = this.parseAlt();
+            if (this.peek() !== ")")
+                this.fail("unterminated group");
+            this.pos += 1;
+            return inner;
+        }
+        if (c === "[")
+            return this.parseClass();
+        if (c === ".") {
+            this.pos += 1;
+            return { kind: "charset", ranges: LINE_TERMINATORS, negated: true };
+        }
+        if (c === "^") {
+            this.pos += 1;
+            return { kind: "assert", end: false };
+        }
+        if (c === "$") {
+            this.pos += 1;
+            return { kind: "assert", end: true };
+        }
+        if (c === "\\") {
+            const code = this.parseEscape();
+            return { kind: "charset", ranges: [[code, code]], negated: false };
+        }
+        if ("*+?{".includes(c))
+            this.fail("quantifier without a preceding atom");
+        if ("]}".includes(c))
+            this.fail(`unbalanced '${c}'`);
+        this.pos += 1;
+        const code = c.codePointAt(0);
+        return { kind: "charset", ranges: [[code, code]], negated: false };
+    }
+    /** Consume a backslash escape and return its code point. */
+    parseEscape() {
+        const e = this.peek(1);
+        if (e === "")
+            this.fail("pattern ends with a backslash");
+        if (PUNCT_ESCAPES.has(e)) {
+            this.pos += 2;
+            return e.codePointAt(0);
+        }
+        if (e in SIMPLE_ESCAPES) {
+            this.pos += 2;
+            return SIMPLE_ESCAPES[e].codePointAt(0);
+        }
+        if (e === "x" || e === "u") {
+            const width = e === "x" ? 2 : 4;
+            const digits = this.chars
+                .slice(this.pos + 2, this.pos + 2 + width)
+                .join("");
+            if (digits.length !== width || [...digits].some((ch) => !HEX.has(ch)))
+                this.fail(`\\${e} escape needs ${width} hex digits`);
+            this.pos += 2 + width;
+            return parseInt(digits, 16);
+        }
+        this.fail(/^[a-z0-9]$/i.test(e)
+            ? `unsupported escape '\\${e}'`
+            : "unsupported escape");
+    }
+    parseClass() {
+        const start = this.pos;
+        this.pos += 1;
+        let negated = false;
+        if (this.peek() === "^") {
+            negated = true;
+            this.pos += 1;
+        }
+        const ranges = [];
+        for (;;) {
+            const c = this.peek();
+            if (c === "")
+                this.fail("unterminated character class");
+            if (c === "]")
+                break;
+            if (c === "[")
+                this.fail("nested character class");
+            const low = this.parseClassChar();
+            if (this.peek() === "-" && this.peek(1) !== "]" && this.peek(1) !== "") {
+                this.pos += 1;
+                const high = this.parseClassChar();
+                if (high < low)
+                    this.fail("inverted character range");
+                ranges.push([low, high]);
+            }
+            else {
+                ranges.push([low, low]);
+            }
+        }
+        const body = this.chars.slice(start + 1, this.pos).join("");
+        if (CLASS_SET_OPS.some((op) => body.includes(op)))
+            this.fail("ambiguous character class operator");
+        this.pos += 1;
+        if (ranges.length === 0)
+            this.fail("empty character class");
+        return { kind: "charset", ranges, negated };
+    }
+    parseClassChar() {
+        if (this.peek() === "\\")
+            return this.parseEscape();
+        const code = this.peek().codePointAt(0);
+        this.pos += 1;
+        return code;
+    }
+    parseQuantifier(atom) {
+        const c = this.peek();
+        let low;
+        let high;
+        if (c === "*") {
+            [low, high] = [0, null];
+            this.pos += 1;
+        }
+        else if (c === "+") {
+            [low, high] = [1, null];
+            this.pos += 1;
+        }
+        else if (c === "?") {
+            [low, high] = [0, 1];
+            this.pos += 1;
+        }
+        else if (c === "{") {
+            [low, high] = this.parseBraces();
+        }
+        else {
+            return atom;
+        }
+        if (atom.kind === "assert")
+            this.fail("anchors cannot be quantified");
+        if (this.peek() === "?")
+            this.pos += 1; // lazy: same language for match/no-match
+        if (this.peek() !== "" && "*+?{".includes(this.peek()))
+            this.fail("stacked or possessive quantifier");
+        return { kind: "repeat", node: atom, low, high };
+    }
+    parseBraces() {
+        const end = this.chars.indexOf("}", this.pos);
+        if (end === -1)
+            this.fail("unsupported '{' outside a bounded quantifier");
+        const parts = this.chars
+            .slice(this.pos + 1, end)
+            .join("")
+            .split(",");
+        const isDigits = (s) => /^[0-9]+$/.test(s);
+        if (parts.length > 2 ||
+            !isDigits(parts[0]) ||
+            (parts.length === 2 && parts[1] !== "" && !isDigits(parts[1])))
+            this.fail("unsupported '{' outside a bounded quantifier");
+        const low = parseInt(parts[0], 10);
+        let high;
+        if (parts.length === 1)
+            high = low;
+        else
+            high = parts[1] ? parseInt(parts[1], 10) : null;
+        if (low > MAX_PATTERN_REPETITION ||
+            (high !== null && high > MAX_PATTERN_REPETITION))
+            this.fail("repetition count is too large");
+        if (high !== null && high < low)
+            this.fail("repetition range is inverted");
+        this.pos = end + 1;
+        return [low, high];
+    }
+}
+// --- shared bounded-compile guard --------------------------------------------
+/**
+ * Enforce the nested-repetition product and the expansion work cap on the AST,
+ * returning the node's expansion size. Identical arithmetic to the Python
+ * `_check_budget`, so both sides accept and reject the same patterns.
+ */
+function checkBudget(node, product = 1) {
+    let size;
+    if (node.kind === "charset" || node.kind === "assert") {
+        return 1;
+    }
+    else if (node.kind === "seq") {
+        size = node.items.reduce((sum, item) => sum + checkBudget(item, product), 0);
+    }
+    else if (node.kind === "alt") {
+        size =
+            node.branches.reduce((sum, branch) => sum + checkBudget(branch, product), 0) +
+                node.branches.length -
+                1;
+    }
+    else {
+        const factor = Math.max(node.high !== null ? node.high : node.low, 1);
+        const nested = product * factor;
+        if (nested > MAX_NESTED_REPETITION)
+            throw new PatternError("unsupported pattern: repetition too large");
+        const body = checkBudget(node.node, nested);
+        if (node.high === null)
+            size = node.low === 0 ? 2 + body : 1 + node.low * body;
+        else
+            size = node.high * body + (node.high - node.low);
+    }
+    size = Math.max(1, size);
+    if (size > MAX_PATTERN_EXPANSION)
+        throw new PatternError("unsupported pattern: too complex");
+    return size;
+}
+function parse(pattern) {
+    if (Array.from(pattern).length > MAX_PATTERN_LENGTH)
+        throw new PatternError("unsupported pattern: pattern is too long");
+    const ast = new Parser(pattern).parse();
+    checkBudget(ast);
+    return ast;
+}
+// --- Rust emitter ------------------------------------------------------------
+function hex(code) {
+    return `\\x{${code.toString(16).toUpperCase()}}`;
+}
+function emit(node) {
+    if (node.kind === "charset") {
+        if (!node.negated &&
+            node.ranges.length === 1 &&
+            node.ranges[0][0] === node.ranges[0][1])
+            return hex(node.ranges[0][0]);
+        const body = node.ranges
+            .map(([low, high]) => low === high ? hex(low) : `${hex(low)}-${hex(high)}`)
+            .join("");
+        return `[${node.negated ? "^" : ""}${body}]`;
+    }
+    if (node.kind === "assert")
+        return node.end ? "\\z" : "^";
+    if (node.kind === "seq")
+        return node.items.map(emitInSeq).join("") || "(?:)";
+    if (node.kind === "alt")
+        return "(?:" + node.branches.map(emit).join("|") + ")";
+    let body = emit(node.node);
+    if (node.node.kind !== "charset")
+        body = `(?:${body})`;
+    if (node.high === null)
+        return (body + (node.low === 0 ? "*" : node.low === 1 ? "+" : `{${node.low},}`));
+    if (node.low === 0 && node.high === 1)
+        return body + "?";
+    return (body +
+        (node.low === node.high ? `{${node.low}}` : `{${node.low},${node.high}}`));
+}
+function emitInSeq(node) {
+    const text = emit(node);
+    return node.kind === "seq" ? `(?:${text})` : text;
+}
+// --- compiled pattern --------------------------------------------------------
+/** A compiled portable pattern executed by the re2js (RE2) engine. */
+export class PortablePattern {
+    source;
+    rust;
+    compiled;
+    constructor(source, rust, compiled) {
+        this.source = source;
+        this.rust = rust;
+        this.compiled = compiled;
+    }
+    /**
+     * True when the pattern matches anywhere in `text` (unanchored, like Python
+     * `re.search` / rust-regex `is_match` and JavaScript `RegExp.prototype.test`).
+     */
+    search(text) {
+        return this.compiled.matcher(text).find();
+    }
+}
+/**
+ * Parse `pattern` against the portable subset and compile it for the
+ * linear-time engine; throws `PatternError` (never echoing input strings).
+ */
+export function compilePattern(pattern) {
+    const rust = emit(parse(pattern));
+    let compiled;
+    try {
+        compiled = RE2JS.compile(rust);
+    }
+    catch {
+        throw new PatternError("unsupported pattern: too complex");
+    }
+    return new PortablePattern(pattern, rust, compiled);
+}
+/** The explicit Rust-syntax form of a portable pattern (tests and export). */
+export function toRustSyntax(pattern) {
+    return emit(parse(pattern));
+}
+/** The shared work metric of a portable pattern (tests and parity checks). */
+export function expansionSize(pattern) {
+    return checkBudget(parse(pattern));
+}

package/dist/validation/schema.d.ts

@@ -0,0 +1,103 @@
+import { type JsonObject, type JsonPath, type JsonValue } from "./json.ts";
+export declare const SUPPORTED_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export declare const MAX_SCHEMA_NODES = 10000;
+export declare const MAX_SCHEMA_DEPTH = 32;
+/** Longest permitted chain of definitions reachable through `$ref` hops. */
+export declare const MAX_REF_CHAIN_DEPTH = 32;
+export declare const MAX_VALIDATION_ERRORS = 20;
+export declare const MAX_SAFE_INTEGER_EXACT: number;
+export declare const MAX_ENUM_VALUES = 256;
+export declare const MAX_UNION_BRANCHES = 64;
+export declare const MAX_TEXT_LENGTH = 4096;
+export declare const MAX_PROPERTY_NAME_LENGTH = 256;
+/** Base for schema definition and validation failures. */
+export declare class SchemaError extends Error {
+    readonly code: string;
+    readonly path: JsonPath;
+    readonly schemaPath: SchemaPath;
+    readonly keyword: string | undefined;
+    constructor(code: string, message: string, options?: {
+        path?: JsonPath;
+        schemaPath?: SchemaPath;
+        keyword?: string;
+    });
+}
+/** The schema document is outside the supported dialect or inconsistent. */
+export declare class SchemaDefinitionError extends SchemaError {
+    constructor(code: string, message: string, options?: {
+        schemaPath?: SchemaPath;
+        keyword?: string;
+    });
+}
+/** A value does not conform to the compiled schema. */
+export declare class SchemaValidationError extends SchemaError {
+    constructor(code: string, message: string, options?: {
+        path?: JsonPath;
+        keyword?: string;
+    });
+}
+export type SchemaPath = ReadonlyArray<string | number>;
+declare class Compiler {
+    private readonly schema;
+    readonly defs: Map<string, JsonObject>;
+    private readonly refEdges;
+    readonly unions: Map<string, {
+        node: JsonObject;
+        path: SchemaPath;
+    }>;
+    readonly defaults: Map<string, {
+        path: SchemaPath;
+        value: JsonValue;
+    }>;
+    constructor(schema: JsonObject);
+    private fail;
+    private expectDict;
+    private checkAnnotations;
+    private rejectUnknown;
+    compile(): void;
+    private normalize;
+    private rewriteTypeList;
+    private normalizeNullable;
+    private normalizeUnion;
+    private normalizeTyped;
+    private normalizeObject;
+    private checkLengthPair;
+    private checkNumericKeywords;
+    private checkAcyclic;
+}
+/** An immutable compiled schema. Construct through {@link compileSchema}. */
+export declare class CompiledSchema {
+    private readonly schema;
+    private readonly defs;
+    private readonly unions;
+    private readonly defaults;
+    private readonly hasDefaults;
+    private readonly validator;
+    private constructor();
+    static build(compiler: Compiler, schema: JsonObject): CompiledSchema;
+    /** A fresh detached copy of the canonical schema. */
+    get canonicalSchema(): JsonObject;
+    get isObject(): boolean;
+    private resolve;
+    /**
+     * Return a detached canonical copy of `value` if it conforms. With
+     * `applyDefaults` the copy first receives defaults for absent object
+     * properties (choosing a union branch only by its discriminator).
+     */
+    validate(value: JsonValue, options?: {
+        applyDefaults?: boolean;
+    }): JsonValue;
+    private fill;
+    private resolveFrom;
+    private measuredCache;
+    private measuredDefault;
+    /** Publication check: every default conforms to its property schema. */
+    private validateDefaults;
+    /** A node reparented under the root's `$defs` so its `$ref`s still resolve. */
+    private subSchema;
+    /** Follow a normalized schema path from the root, resolving `$ref` hops. */
+    private locate;
+}
+/** Compile a schema document into an immutable {@link CompiledSchema}. */
+export declare function compileSchema(schema: unknown): CompiledSchema;
+export {};