@m6d/cortex-cli 0.23.0 → 0.24.0

package/src/contracts/manifest/index.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { datasetIdentifierSchema } from "../datasets/index";
 import { canCarrySecret } from "../egress-policy/index";
+import { isRecord } from "../json/index";
+import { linearPattern } from "../pattern/index";
 import { triggerScheduleSchema } from "../schedule/index";
 import {
     displayNameSchema,
@@ -677,47 +679,251 @@ const propertyOrderSchema = z
     .refine((names) => new Set(names).size === names.length, "a name repeats")
     .optional();
 
-/** What an array holds: a scalar, or an object with properties of its own. */
-const itemsSchema = z.strictObject({
-    type: z.enum([...SCALAR_TYPES, "object"]),
-    get properties() {
-        return z.record(propertyNameSchema, schemaPropertySchema).optional();
-    },
-    required: z.array(z.string()).optional(),
-    "x-order": propertyOrderSchema,
+const countSchema = z.number().int().min(0).optional();
+
+/**
+ * The JSON Schema keywords that bound one value beyond its type and enum:
+ * a string's `pattern` (one RE2 can match, as Cortex checks it) and lengths,
+ * a scalar's `format` (kept for the model, not checked), a number's range and step, an
+ * array's length and uniqueness, and a scalar's `const`.
+ */
+export const valueKeywordsSchema = z.strictObject({
+    pattern: z
+        .string()
+        .min(1)
+        .max(1_000)
+        .refine((pattern) => linearPattern(pattern) !== undefined, "a pattern Cortex cannot match")
+        .optional(),
+    minLength: countSchema,
+    maxLength: countSchema,
+    format: z.string().trim().min(1).max(100).optional(),
+    minimum: z.number().optional(),
+    maximum: z.number().optional(),
+    exclusiveMinimum: z.number().optional(),
+    exclusiveMaximum: z.number().optional(),
+    multipleOf: z.number().positive().optional(),
+    minItems: countSchema,
+    maxItems: countSchema,
+    uniqueItems: z.boolean().optional(),
+    const: z.union([z.string().max(4_000), z.number(), z.boolean()]).optional(),
 });
+export type ValueKeywords = z.infer<typeof valueKeywordsSchema>;
+
+const NUMERIC_TYPES = ["number", "integer"];
+
+/** The types each value keyword bounds; on any other it means nothing. */
+export const VALUE_KEYWORD_TYPES = {
+    pattern: ["string"],
+    minLength: ["string"],
+    maxLength: ["string"],
+    format: SCALAR_TYPES,
+    minimum: NUMERIC_TYPES,
+    maximum: NUMERIC_TYPES,
+    exclusiveMinimum: NUMERIC_TYPES,
+    exclusiveMaximum: NUMERIC_TYPES,
+    multipleOf: NUMERIC_TYPES,
+    minItems: ["array"],
+    maxItems: ["array"],
+    uniqueItems: ["array"],
+    const: SCALAR_TYPES,
+} satisfies Record<keyof ValueKeywords, ReadonlyArray<string>>;
+
+/** The types a rule tests a value for: `"null"` too, since a rule may tell a null apart. */
+const ruleTypeSchema = z.enum([...SCALAR_TYPES, "object", "array", "null"]);
+type RuleType = z.infer<typeof ruleTypeSchema>;
+
+/**
+ * An object's cross-field rules: which properties go together (`anyOf`,
+ * `oneOf`, `allOf`, `not`, `if`/`then`/`else`, `dependentRequired`,
+ * `dependentSchemas`) and how many it holds. A rule names the object's own
+ * properties only.
+ */
+export type ObjectRules = {
+    anyOf?: Condition[];
+    oneOf?: Condition[];
+    allOf?: Condition[];
+    not?: Condition;
+    if?: Condition;
+    then?: Condition;
+    else?: Condition;
+    dependentRequired?: Record<string, string[]>;
+    dependentSchemas?: Record<string, Condition>;
+    minProperties?: number;
+    maxProperties?: number;
+};
+
+/**
+ * A schema a rule checks its object against, in the part of JSON Schema a
+ * rule reads: what it requires, its properties' types, enums and value
+ * keywords, an array's items, and rules of its own.
+ */
+type Condition = ValueKeywords &
+    ObjectRules & {
+        type?: RuleType | RuleType[];
+        enum?: Array<string | number | boolean | null>;
+        required?: string[];
+        properties?: Record<string, Condition>;
+        items?: Condition;
+    };
+
+const conditionSchema: z.ZodType<Condition, Condition> = z
+    .lazy(() =>
+        z.strictObject({
+            type: z.union([ruleTypeSchema, z.array(ruleTypeSchema).min(1)]).optional(),
+            enum: z
+                .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .min(1)
+                .optional(),
+            ...valueKeywordsSchema.shape,
+            required: z.array(z.string()).optional(),
+            properties: z.record(z.string(), conditionSchema).optional(),
+            items: conditionSchema.optional(),
+            ...objectRulesSchema.shape,
+        }),
+    )
+    .meta({ id: "SchemaCondition" });
+
+/** The members of a rule's `anyOf`, `oneOf` or `allOf`. */
+const conditionsSchema = z.array(conditionSchema).min(1).meta({ id: "SchemaConditions" });
+
+export const objectRulesSchema = z.strictObject({
+    anyOf: conditionsSchema.optional(),
+    oneOf: conditionsSchema.optional(),
+    allOf: conditionsSchema.optional(),
+    not: conditionSchema.optional(),
+    if: conditionSchema.optional(),
+    then: conditionSchema.optional(),
+    else: conditionSchema.optional(),
+    dependentRequired: z.record(z.string(), z.array(z.string())).optional(),
+    dependentSchemas: z.record(z.string(), conditionSchema).optional(),
+    minProperties: countSchema,
+    maxProperties: countSchema,
+}) satisfies z.ZodType<ObjectRules>;
+
+/** The keywords that check an object's properties against each other. */
+export const OBJECT_RULE_KEYWORDS = objectRulesSchema.keyof().options;
+
+/** A rule keyword's array value, or none when it holds no array. */
+function listed(value: unknown) {
+    return Array.isArray(value) ? (value as unknown[]) : [];
+}
+
+/** A rule keyword's map value, or an empty one when it holds no map. */
+function keyed(value: unknown) {
+    return isRecord(value) ? value : {};
+}
+
+/**
+ * A rule and every rule nested in it that checks the same object, through
+ * its combinators, `not`, `if`/`then`/`else` and `dependentSchemas`, but
+ * not inside a property's own value.
+ */
+export function ruleNodes(rule: unknown): Array<Record<string, unknown>> {
+    if (!isRecord(rule)) return [];
+    return [
+        rule,
+        ...[
+            ...["anyOf", "oneOf", "allOf"].flatMap((keyword) => listed(rule[keyword])),
+            rule.not,
+            rule.if,
+            rule.then,
+            rule.else,
+            ...Object.values(keyed(rule.dependentSchemas)),
+        ].flatMap(ruleNodes),
+    ];
+}
+
+/**
+ * The property names a rule reaches on the object it checks: those any of
+ * its nodes (`ruleNodes`) requires, reads or makes depend on each other.
+ */
+export function ruleNames(rule: unknown) {
+    return ruleNodes(rule)
+        .flatMap((node) => [
+            ...listed(node.required),
+            ...Object.keys(keyed(node.properties)),
+            ...Object.entries(keyed(node.dependentRequired)).flatMap(([name, names]) => [
+                name,
+                ...listed(names),
+            ]),
+            ...Object.keys(keyed(node.dependentSchemas)),
+        ])
+        .filter((name): name is string => typeof name === "string");
+}
+
+/** What an array holds: a scalar (a string's values listed in `enum`, as a property's), or an object with properties of its own; with `"null"` beside its type when an item may be null. */
+type SchemaItems = ValueKeywords &
+    ObjectRules & {
+        type: ItemType | [ItemType, "null"];
+        enum?: Array<string | null>;
+        properties?: Record<string, SchemaProperty>;
+        required?: string[];
+        "x-order"?: string[];
+    };
 
 /**
  * A JSON Schema property, in the part of JSON Schema a field editor holds:
  * a type (with `"null"` beside it when the value may be null), an `enum` of
  * strings for a string, an object's `properties`, `required` and the
- * `x-order` they are shown in, an array's `items`, a `description`, and
- * the extensions `x-sensitive` (redacted from logs), `x-source` (top-level
- * scalar fields of a tool's input only) and `x-target` (top-level fields of
- * a tool's input only).
+ * `x-order` they are shown in, an array's `items`, a `description`, the
+ * value keywords its type takes (`VALUE_KEYWORD_TYPES`), an object's rules,
+ * and the extensions `x-sensitive` (redacted from logs), `x-source`
+ * (top-level scalar fields of a tool's input only) and `x-target` (top-level
+ * fields of a tool's input only).
  */
-const schemaPropertySchema = z.strictObject({
-    type: z.union([schemaTypeSchema, z.tuple([schemaTypeSchema, z.literal("null")])]),
-    description: z.string().trim().max(FIELD_LIMITS.descriptionLength).optional(),
-    /** A nullable enum lists `null` beside its values, as the console stores one. */
-    enum: z
-        .array(z.union([z.string().trim().min(1), z.null()]))
-        .min(1)
-        .max(FIELD_LIMITS.enumValues + 1)
-        .optional(),
-    get properties() {
-        return z.record(propertyNameSchema, schemaPropertySchema).optional();
-    },
-    required: z.array(z.string()).optional(),
-    "x-order": propertyOrderSchema,
-    get items() {
-        return itemsSchema.optional();
-    },
-    "x-sensitive": z.boolean().optional(),
-    "x-source": fieldSourceSchema.optional(),
-    "x-target": fieldTargetSchema.optional(),
-});
-type SchemaProperty = z.infer<typeof schemaPropertySchema>;
+type SchemaProperty = ValueKeywords &
+    ObjectRules & {
+        type: SchemaType | [SchemaType, "null"];
+        description?: string;
+        /** A nullable enum lists `null` beside its values, as the console stores one. */
+        enum?: Array<string | null>;
+        properties?: Record<string, SchemaProperty>;
+        required?: string[];
+        "x-order"?: string[];
+        items?: SchemaItems;
+        "x-sensitive"?: boolean;
+        "x-source"?: FieldSource;
+        "x-target"?: FieldTarget;
+    };
+type SchemaType = z.infer<typeof schemaTypeSchema>;
+const itemTypeSchema = z.enum([...SCALAR_TYPES, "object"]);
+type ItemType = z.infer<typeof itemTypeSchema>;
+
+/** A nullable enum lists `null` beside its values, as the console stores one. */
+const enumSchema = z
+    .array(z.union([z.string().trim().min(1), z.null()]))
+    .min(1)
+    .max(FIELD_LIMITS.enumValues + 1)
+    .optional();
+
+const itemsSchema: z.ZodType<SchemaItems, SchemaItems> = z.lazy(() =>
+    z.strictObject({
+        type: z.union([itemTypeSchema, z.tuple([itemTypeSchema, z.literal("null")])]),
+        enum: enumSchema,
+        properties: z.record(propertyNameSchema, schemaPropertySchema).optional(),
+        required: z.array(z.string()).optional(),
+        "x-order": propertyOrderSchema,
+        ...valueKeywordsSchema.shape,
+        ...objectRulesSchema.shape,
+    }),
+);
+
+const schemaPropertySchema: z.ZodType<SchemaProperty, SchemaProperty> = z.lazy(() =>
+    z.strictObject({
+        type: z.union([schemaTypeSchema, z.tuple([schemaTypeSchema, z.literal("null")])]),
+        description: z.string().trim().max(FIELD_LIMITS.descriptionLength).optional(),
+        enum: enumSchema,
+        properties: z.record(propertyNameSchema, schemaPropertySchema).optional(),
+        required: z.array(z.string()).optional(),
+        "x-order": propertyOrderSchema,
+        items: itemsSchema.optional(),
+        "x-sensitive": z.boolean().optional(),
+        "x-source": fieldSourceSchema.optional(),
+        "x-target": fieldTargetSchema.optional(),
+        ...valueKeywordsSchema.shape,
+        ...objectRulesSchema.shape,
+    }),
+);
 
 /** A node's own type, without the `"null"` beside it. */
 function typeOf(node: { type: SchemaProperty["type"] }) {
@@ -728,29 +934,45 @@ function typeOf(node: { type: SchemaProperty["type"] }) {
 type RowIssue = { at: Array<string | number>; message: string };
 
 /** A node holding properties: a property, an array's items, or an input or output schema. */
-type ObjectNode = {
-    type: SchemaProperty["type"];
-    properties?: Record<string, SchemaProperty>;
-    required?: string[];
-    "x-order"?: string[];
-};
+type ObjectNode = ObjectRules &
+    ValueKeywords & {
+        type: SchemaProperty["type"];
+        properties?: Record<string, SchemaProperty>;
+        required?: string[];
+        "x-order"?: string[];
+    };
 
-/** What a node's own keywords break: `properties`, `required` or `x-order` off an object, or the last two naming no property. */
+/**
+ * What a node's own keywords break: `properties`, `required`, `x-order` or
+ * a rule off an object, the next two or a rule naming no property, and a
+ * value keyword off the types it bounds.
+ */
 function nodeIssues(node: ObjectNode) {
     const issues = new Array<RowIssue>();
-    const object = typeOf(node) === "object";
-    for (const keyword of ["properties", "required", "x-order"] as const) {
+    const type = typeOf(node);
+    const object = type === "object";
+    for (const keyword of ["properties", "required", "x-order", ...OBJECT_RULE_KEYWORDS] as const) {
         if (!object && node[keyword] !== undefined) {
             issues.push({ at: [keyword], message: "only an object has it" });
         }
     }
+    const named = (name: string) => Object.hasOwn(node.properties ?? {}, name);
     for (const keyword of ["required", "x-order"] as const) {
         node[keyword]?.forEach((name, index) => {
-            if (!Object.hasOwn(node.properties ?? {}, name)) {
-                issues.push({ at: [keyword, index], message: "names no property" });
-            }
+            if (!named(name)) issues.push({ at: [keyword, index], message: "names no property" });
         });
     }
+    for (const keyword of OBJECT_RULE_KEYWORDS) {
+        if (object && !ruleNames({ [keyword]: node[keyword] }).every(named)) {
+            issues.push({ at: [keyword], message: "names no property" });
+        }
+    }
+    for (const [keyword, types] of Object.entries(VALUE_KEYWORD_TYPES)) {
+        if (node[keyword as keyof ValueKeywords] === undefined) continue;
+        if (!types.some((bounded) => bounded === type)) {
+            issues.push({ at: [keyword], message: `only a ${types.join(" or ")} has it` });
+        }
+    }
     return issues;
 }
 
@@ -759,7 +981,7 @@ function nodeIssues(node: ObjectNode) {
  * them, beside `null` exactly when the type allows null, as the console
  * stores a nullable one.
  */
-function enumIssueOf(property: SchemaProperty, type: string | undefined) {
+function enumIssueOf(property: Pick<SchemaProperty, "enum" | "type">, type: string | undefined) {
     if (property.enum === undefined) return undefined;
     if (type !== "string") return "an enum lists a string's values";
     const values = property.enum.filter((value) => value !== null);
@@ -854,7 +1076,10 @@ function heldByRows(
         const at = [...path, "properties", name];
         report(at, propertyIssues(property, bindings));
         heldByRows(property, context, at, undefined);
-        if (property.items) heldByRows(property.items, context, [...at, "items"], undefined);
+        if (!property.items) continue;
+        const enumIssue = enumIssueOf(property.items, typeOf(property.items));
+        if (enumIssue) report([...at, "items"], [{ at: ["enum"], message: enumIssue }]);
+        heldByRows(property.items, context, [...at, "items"], undefined);
     }
 }
 
@@ -862,7 +1087,8 @@ function heldByRows(
  * An object's JSON Schema, the shape of a tool's or trigger's input and
  * output, and of what the console's field rows write. `bindings`, given for
  * a tool's input, are the extensions its top-level fields may carry:
- * `x-source` on a scalar, `x-target` on any field.
+ * `x-source` on a scalar, `x-target` on any field. Only a tool's input holds
+ * rules at its root, as the console keeps them beside its rows.
  */
 export function objectJsonSchemaOf(bindings?: ReadonlyArray<Binding>) {
     return z
@@ -871,8 +1097,20 @@ export function objectJsonSchemaOf(bindings?: ReadonlyArray<Binding>) {
             properties: z.record(propertyNameSchema, schemaPropertySchema).optional(),
             required: z.array(z.string()).optional(),
             "x-order": propertyOrderSchema,
+            ...objectRulesSchema.shape,
         })
-        .superRefine((schema, context) => heldByRows(schema, context, [], bindings));
+        .superRefine((schema, context) => {
+            heldByRows(schema, context, [], bindings);
+            if (bindings !== undefined) return;
+            for (const keyword of OBJECT_RULE_KEYWORDS) {
+                if (schema[keyword] === undefined) continue;
+                context.addIssue({
+                    code: "custom",
+                    path: [keyword],
+                    message: "only a tool's input has rules at its root",
+                });
+            }
+        });
 }
 const objectSchema = objectJsonSchemaOf();
 

package/src/contracts/pattern/index.ts

@@ -0,0 +1,276 @@
+// cspell:ignore fefe fff
+import { RE2JS } from "re2js";
+
+/*
+ * A tool input schema's `pattern`: a regular expression JavaScript reads with
+ * no flags, which Cortex matches on RE2 so a value is checked in time linear
+ * in its length. A pattern RE2 cannot match as JavaScript reads it is refused
+ * by Cortex and left out of what the TypeScript SDK exports.
+ *
+ * RE2 matches code points where JavaScript matches UTF-16 units, so the
+ * pattern and every input lift each surrogate unit into a private-use plane,
+ * where it is one code point: RE2 then reads the units JavaScript reads.
+ * Nothing collides there, since a real character in that plane is astral,
+ * arrives as two surrogate units and is lifted in turn.
+ */
+
+/**
+ * What one escape or character in a class stands for, spelled as the inside
+ * of an RE2 class: a single character carries its UTF-16 unit, and an
+ * unescaped `-` is marked as one that may make a range.
+ */
+type Atom = { body: string; char?: number; dash?: boolean };
+
+/** JavaScript's `\s`, its WhiteSpace and LineTerminator characters, as the inside of an RE2 class. */
+const SPACE =
+    "\\x{9}-\\x{d}\\x{20}\\x{a0}\\x{1680}\\x{2000}-\\x{200a}\\x{2028}\\x{2029}\\x{202f}\\x{205f}\\x{3000}\\x{feff}";
+/** Every character `SPACE` leaves out: JavaScript's `\S`. */
+const NON_SPACE =
+    "\\x{0}-\\x{8}\\x{e}-\\x{1f}\\x{21}-\\x{9f}\\x{a1}-\\x{167f}\\x{1681}-\\x{1fff}\\x{200b}-\\x{2027}" +
+    "\\x{202a}-\\x{202e}\\x{2030}-\\x{205e}\\x{2060}-\\x{2fff}\\x{3001}-\\x{fefe}\\x{ff00}-\\x{10ffff}";
+/** The set escapes as JavaScript reads them; RE2's own `\d` and `\w` match, its `\s` holds only ASCII. */
+const SET_ESCAPES = new Map([
+    ["d", "\\d"],
+    ["D", "\\D"],
+    ["w", "\\w"],
+    ["W", "\\W"],
+    ["s", SPACE],
+    ["S", NON_SPACE],
+]);
+/** JavaScript's `.`: every character but a line terminator, where RE2's leaves out only `\n`. */
+const DOT = "[^\\x{a}\\x{d}\\x{2028}\\x{2029}]";
+const CONTROL_ESCAPES = new Map([
+    ["f", 0x0c],
+    ["n", 0x0a],
+    ["r", 0x0d],
+    ["t", 0x09],
+    ["v", 0x0b],
+]);
+const QUANTIFIER = /\{\d+(?:,\d*)?\}/y;
+const SURROGATE = /[\uD800-\uDFFF]/g;
+/** Where surrogate unit `0xd800 + n` is lifted: code point `0xf0000 + n`. */
+const LIFTED_SURROGATES = 0xf0000;
+const HEX = /[0-9A-Fa-f]+/y;
+/** What JavaScript's `[^]` and `[]` hold: every character, and none. */
+const ANY = "[\\x{0}-\\x{10ffff}]";
+const NONE = "[^\\x{0}-\\x{10ffff}]";
+
+/** A thrown error: the pattern holds what RE2 cannot match as JavaScript reads it. */
+function unsupported(what: string): never {
+    throw new Error(`a pattern with ${what}`);
+}
+
+/** A UTF-16 unit as the one code point RE2 reads: a surrogate lifted, any other unit itself. */
+function lifted(unit: number) {
+    return unit >= 0xd800 && unit <= 0xdfff ? LIFTED_SURROGATES + unit - 0xd800 : unit;
+}
+
+/** `input` with every surrogate unit lifted, one code point per UTF-16 unit. */
+function liftedText(input: string) {
+    return input.replace(SURROGATE, (unit) => String.fromCodePoint(lifted(unit.charCodeAt(0))));
+}
+
+/** One UTF-16 unit as RE2 reads it literally, inside a class or out. */
+function literal(unit: number) {
+    const char = lifted(unit);
+    const spelled = String.fromCodePoint(char);
+    return /^[A-Za-z0-9]$/.test(spelled) ? spelled : `\\x{${char.toString(16)}}`;
+}
+
+/**
+ * The units from `from` to `to` as the inside of an RE2 class: the part
+ * among the surrogates, lifted, apart from the parts below and above it.
+ */
+function unitRange(from: number, to: number) {
+    return (
+        [
+            [from, Math.min(to, 0xd7ff)],
+            [Math.max(from, 0xd800), Math.min(to, 0xdfff)],
+            [Math.max(from, 0xe000), to],
+        ] satisfies Array<[number, number]>
+    )
+        .filter(([low, high]) => low <= high)
+        .map(([low, high]) => `${literal(low)}-${literal(high)}`)
+        .join("");
+}
+
+function character(char: number, dash = false) {
+    return { body: literal(char), char, dash };
+}
+
+/**
+ * A class's atoms as the inside of an RE2 class: an unescaped dash between
+ * two characters makes a range, and beside a set escape it is a character,
+ * as JavaScript reads them.
+ */
+function classBody(atoms: Atom[]) {
+    let body = "";
+    for (let index = 0; index < atoms.length; index += 1) {
+        const [from, dash, to] = atoms.slice(index, index + 3);
+        if (!from) break;
+        if (!dash?.dash || !to) {
+            body += from.body;
+            continue;
+        }
+        body +=
+            from.char !== undefined && to.char !== undefined
+                ? unitRange(from.char, to.char)
+                : `${from.body}${dash.body}${to.body}`;
+        index += 2;
+    }
+    return body;
+}
+
+/**
+ * A pattern read left to right as JavaScript reads it with no flags (Annex B
+ * included), written in RE2's syntax; throws on a lookaround, a
+ * backreference, a legacy octal escape, a group modifier or a `\c` without
+ * its letter. It reads UTF-16 units, as JavaScript does. Groups do not
+ * capture: nothing reads them.
+ */
+class Translation {
+    private at = 0;
+
+    public constructor(private readonly pattern: string) {}
+
+    public spell() {
+        let re2 = "";
+        while (this.at < this.pattern.length) re2 += this.term();
+        return re2;
+    }
+
+    private term() {
+        const char = this.pattern[this.at] ?? "";
+        if (char === "\\") return this.escapeOutsideClass();
+        if (char === "[") return this.characterClass();
+        if (char === "(") return this.group();
+        if (char === "{") return this.brace();
+        if (!"|)^$*+?.".includes(char)) return literal(this.unit());
+        this.at += 1;
+        return char === "." ? DOT : char;
+    }
+
+    private escapeOutsideClass() {
+        this.at += 1;
+        const assertion = this.pattern[this.at];
+        if (assertion === "b" || assertion === "B") {
+            this.at += 1;
+            return `\\${assertion}`;
+        }
+        const atom = this.escape(false);
+        return "char" in atom ? atom.body : `[${atom.body}]`;
+    }
+
+    /** The escape after a backslash, which `at` is past; in a class `\b` is a backspace. */
+    private escape(insideClass: boolean) {
+        const next = this.pattern[this.at] ?? unsupported("a trailing backslash");
+        this.at += 1;
+        const set = SET_ESCAPES.get(next);
+        if (set) return { body: set };
+        const control = insideClass && next === "b" ? 0x08 : CONTROL_ESCAPES.get(next);
+        if (control !== undefined) return character(control);
+        if (next === "c") return character(this.controlLetter(insideClass));
+        if (next === "x" || next === "u") {
+            return character(this.hex(next === "x" ? 2 : 4) ?? next.charCodeAt(0));
+        }
+        if (next === "0" && !/^\d$/.test(this.pattern[this.at] ?? "")) return character(0);
+        if (/^[\dk]$/.test(next)) unsupported("a backreference or an octal escape");
+        this.at -= 1;
+        return character(this.unit());
+    }
+
+    /** The control character a `\c` names: a letter, or in a class also a digit or `_`. */
+    private controlLetter(insideClass: boolean) {
+        const letter = this.pattern[this.at] ?? "";
+        if (!(insideClass ? /^\w$/ : /^[A-Za-z]$/).test(letter)) {
+            unsupported("a \\c without its letter");
+        }
+        this.at += 1;
+        return letter.charCodeAt(0) % 32;
+    }
+
+    /** `length` hex digits at `at` as a UTF-16 unit, consumed; undefined when fewer follow. */
+    private hex(length: number) {
+        HEX.lastIndex = this.at;
+        const digits = HEX.exec(this.pattern)?.[0] ?? "";
+        if (digits.length < length) return undefined;
+        this.at += length;
+        return Number.parseInt(digits.slice(0, length), 16);
+    }
+
+    private unit() {
+        const unit = this.pattern.charCodeAt(this.at);
+        if (Number.isNaN(unit)) unsupported("a pattern cut short");
+        this.at += 1;
+        return unit;
+    }
+
+    /**
+     * A class, `at` on its `[`. In JavaScript a `]` always closes one, so
+     * `[]` holds nothing and `[^]` everything.
+     */
+    private characterClass() {
+        this.at += 1;
+        const negated = this.pattern[this.at] === "^";
+        if (negated) this.at += 1;
+        const atoms: Atom[] = [];
+        while (this.pattern[this.at] !== "]") {
+            if (this.at >= this.pattern.length) unsupported("an unclosed class");
+            atoms.push(this.classAtom());
+        }
+        this.at += 1;
+        const body = classBody(atoms);
+        if (!body) return negated ? ANY : NONE;
+        return `[${negated ? "^" : ""}${body}]`;
+    }
+
+    private classAtom() {
+        const char = this.pattern[this.at];
+        this.at += 1;
+        if (char === "\\") return this.escape(true);
+        if (char === "-") return character(0x2d, true);
+        this.at -= 1;
+        return character(this.unit());
+    }
+
+    /** A group's opening as RE2 reads it: every group, named or not, without a capture. */
+    private group() {
+        const opening = this.pattern.slice(this.at, this.at + 4);
+        if (/^\(\?<[^=!]/.test(opening)) {
+            const name = this.pattern.indexOf(">", this.at);
+            if (name < 0) unsupported("an unclosed group name");
+            this.at = name + 1;
+        } else if (opening.startsWith("(?")) {
+            if (!opening.startsWith("(?:")) unsupported("a lookaround or a group modifier");
+            this.at += 3;
+        } else {
+            this.at += 1;
+        }
+        return "(?:";
+    }
+
+    /** A quantifier, or a brace JavaScript reads as a character because it opens none. */
+    private brace() {
+        QUANTIFIER.lastIndex = this.at;
+        const quantifier = QUANTIFIER.exec(this.pattern)?.[0];
+        this.at += quantifier?.length ?? 1;
+        return quantifier ?? literal(0x7b);
+    }
+}
+
+/**
+ * A matcher for a pattern JavaScript compiles, meaning what the pattern
+ * means to JavaScript with no flags, UTF-16 unit for unit; undefined when
+ * RE2 cannot match it so, as for a lookaround, a backreference or a
+ * repetition past 1000. Its `test` runs on RE2, in time linear in the input.
+ * It never calls `new RegExp`, so it works while a caller has replaced that
+ * global.
+ */
+export function linearPattern(pattern: string) {
+    try {
+        const re2 = RE2JS.compile(new Translation(pattern).spell());
+        return { test: (input: string) => re2.test(liftedText(input)) };
+    } catch {
+        return undefined;
+    }
+}