diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index 07564cdd27..f8839696ae 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -55,6 +55,14 @@ relative inputs, auxiliary files or output destinations. An empty string never selects the working directory; use an explicit `.` when selecting that directory is supported by the command. +For a numeric option whose `--schema` also accepts decimal strings, the string +branch carries the same numeric range as the integer branch, so a client that +validates raw argv text rejects out-of-range tokens. Leading zeros remain +decimal: `--row-limit=0001` means one row, while `--row-limit=0` is invalid. A +lower bound is still published when the option has no upper bound, so only the +ceiling stays open. Refinements that are not a range, such as requiring a +power-of-two entropy block size, stay parser-only. + For example, a 334 MB Obsidian application Evidence file yields a summary view of about 10 KB. Replace the view with `{"kind": "page", "collection": "modules", "offset": 0, "limit": 32}` for a diff --git a/src/cli/decimalTokenPattern.ts b/src/cli/decimalTokenPattern.ts new file mode 100644 index 0000000000..07e1b30e1f --- /dev/null +++ b/src/cli/decimalTokenPattern.ts @@ -0,0 +1,83 @@ +import { z } from "zod"; + +const digits = (count: number): string => + count === 0 ? "" : count === 1 ? "[0-9]" : `[0-9]{${count}}`; + +const digitRange = (low: number, high: number): string => + low === high ? String(low) : `[${low}-${high}]`; + +/** Lexicographic bounds for equal-width, unsigned decimal strings. */ +const sameWidthRange = (low: string, high: string): string => { + if (low === high) return low; + const width = low.length; + if (low === "0".repeat(width) && high === "9".repeat(width)) + return digits(width); + const first = Number(low[0]); + const last = Number(high[0]); + if (width === 1) return digitRange(first, last); + if ( + low.slice(1) === "0".repeat(width - 1) && + high.slice(1) === "9".repeat(width - 1) + ) + return `${digitRange(first, last)}${digits(width - 1)}`; + if (first === last) + return `${first}${sameWidthRange(low.slice(1), high.slice(1))}`; + const branches = [ + `${first}${sameWidthRange(low.slice(1), "9".repeat(width - 1))}`, + ]; + if (first + 1 <= last - 1) + branches.push(`${digitRange(first + 1, last - 1)}${digits(width - 1)}`); + branches.push( + `${last}${sameWidthRange("0".repeat(width - 1), high.slice(1))}`, + ); + return `(?:${branches.join("|")})`; +}; + +/** Keep the floor of an open-ended domain, whose tokens may grow past it. */ +const openEndedPattern = (minimum: number): string => { + if (minimum === 0) return "^[0-9]+$"; + const low = String(minimum); + const atFloorWidth = sameWidthRange(low, "9".repeat(low.length)); + return `^0*(?:${atFloorWidth}|[1-9][0-9]{${String(low.length)},})$`; +}; + +/** + * Publish the domain's numeric range on the decimal-token branch without + * changing parser diagnostics. Refinements that are not a range stay + * parser-only, so an advertised schema can admit a token the parser rejects; + * it never rejects a token the parser admits. + */ +export const decimalTokenPattern = (domain: z.ZodNumber): string => { + const schema = z.toJSONSchema(domain); + const minimum = Math.max( + 0, + Math.ceil(schema.minimum ?? 0), + typeof schema.exclusiveMinimum === "number" + ? Math.floor(schema.exclusiveMinimum) + 1 + : 0, + ); + const maximum = Math.min( + Math.floor(schema.maximum ?? Infinity), + typeof schema.exclusiveMaximum === "number" + ? Math.ceil(schema.exclusiveMaximum) - 1 + : Infinity, + ); + // Non-integer floors and ceilings have no safe-integer range to publish. + if (!Number.isSafeInteger(minimum)) return "^[0-9]+$"; + if (maximum === Infinity) return openEndedPattern(minimum); + if (!Number.isSafeInteger(maximum)) return "^[0-9]+$"; + if (minimum > maximum) return "^(?!)$"; + const low = String(minimum); + const high = String(maximum); + const branches: string[] = []; + for (let width = low.length; width <= high.length; width++) { + branches.push( + sameWidthRange( + width === low.length ? low : `1${"0".repeat(width - 1)}`, + width === high.length ? high : "9".repeat(width), + ), + ); + } + // Tokens retain the CLI's decimal leading-zero convention. + return `^0*(?:${branches.join("|")})$`; +}; diff --git a/src/cli/options.ts b/src/cli/options.ts index 1674f30b9c..f4190d2e99 100644 --- a/src/cli/options.ts +++ b/src/cli/options.ts @@ -1,5 +1,8 @@ import { z } from "zod"; +import { declaredTokenPattern } from "../domain/schemaConstraints.js"; +import { decimalTokenPattern } from "./decimalTokenPattern.js"; + import { OPEN_BINARY_TOOL_CONTRACT } from "../contracts/sessionToolContracts.js"; import type { CliSessionTarget } from "./contractCliDescription.js"; @@ -14,9 +17,10 @@ type DecimalWrapper = }; const decimalToken = (domain: z.ZodNumber) => - z - .string() - .regex(DECIMAL_INTEGER_TOKEN, "Expected a decimal integer") + declaredTokenPattern( + z.string().regex(DECIMAL_INTEGER_TOKEN, "Expected a decimal integer"), + new RegExp(decimalTokenPattern(domain), "u"), + ) .pipe(z.coerce.number()) .pipe(domain); diff --git a/src/cliDecimalTokenPattern.test.ts b/src/cliDecimalTokenPattern.test.ts new file mode 100644 index 0000000000..44b0f6d70e --- /dev/null +++ b/src/cliDecimalTokenPattern.test.ts @@ -0,0 +1,91 @@ +import { Ajv2020 } from "ajv/dist/2020.js"; +import { z } from "zod"; +import { expect, it } from "vitest"; + +import { cliDecimalField } from "./cli/options.js"; + +it("keeps advertised decimal bounds aligned across decimal-width transitions", () => { + const ajv = new Ajv2020({ strict: false }); + for (const [minimum, maximum] of [ + [0, 0], + [0, 16], + [1, 9], + [8, 12], + [76, 256], + [99, 100], + [256, 65536], + [9007199254740980, Number.MAX_SAFE_INTEGER], + ] as const) { + const domain = z.number().int().min(minimum).max(maximum); + const field = cliDecimalField(domain); + const validate = ajv.compile(z.toJSONSchema(field)); + const candidates = new Set([ + ...Array.from({ length: 1001 }, (_, index) => index), + minimum - 1, + minimum, + minimum + 1, + maximum - 1, + maximum, + maximum + 1, + ]); + for (const value of candidates) { + if (value < 0) continue; + for (const token of [String(value), `000${value}`]) { + expect(validate(token), `${minimum}..${maximum}: ${token}`).toBe( + field.safeParse(token).success, + ); + } + } + for (const token of ["", "1e2", "0x10", "+1", "1.0", "1\n", " 1"]) + expect(validate(token), token).toBe(false); + } +}); + +it("retains exclusive bounds, wrappers, and parser-only refinements", () => { + const ajv = new Ajv2020({ strict: false }); + const field = cliDecimalField( + z.number().int().gt(0).lt(10).nullable().default(2).readonly(), + ); + const validate = ajv.compile(z.toJSONSchema(field)); + for (const value of ["0", "10", "00010", 0, 10]) + expect(validate(value)).toBe(false); + for (const value of ["1", "09", "0009", 1, 9, null]) + expect(validate(value)).toBe(true); + expect(field.parse(undefined)).toBe(2); + expect(field.parse("09")).toBe(9); + expect(field.parse(null)).toBeNull(); + + const refined = cliDecimalField( + z + .number() + .int() + .min(1) + .max(10) + .refine((value) => value % 2 === 0), + ); + expect(ajv.compile(z.toJSONSchema(refined))("3")).toBe(true); + expect(refined.safeParse("3").success).toBe(false); +}); + +it("keeps a positive floor when the domain has no ceiling", () => { + for (const minimum of [1, 5, 10, 256]) { + const field = cliDecimalField(z.number().min(minimum)); + const validate = new Ajv2020({ strict: false }).compile( + z.toJSONSchema(field), + ); + for (const value of [ + minimum - 1, + minimum, + minimum + 1, + 65536, + 9007199254740992, + 1e20, + ]) { + for (const token of [String(value), `000${String(value)}`]) + expect(validate(token), `${String(minimum)}..: ${token}`).toBe( + field.safeParse(token).success, + ); + } + expect(validate("")).toBe(false); + } +}); diff --git a/src/domain/schemaConstraints.ts b/src/domain/schemaConstraints.ts index 7cae1d44e3..a4af91c113 100644 --- a/src/domain/schemaConstraints.ts +++ b/src/domain/schemaConstraints.ts @@ -158,6 +158,16 @@ const declaredPattern = (expression: RegExp): string => { return expression.source; }; +/** + * Declare the pattern an argv token grammar accepts. The grammar's own check + * still rejects every token the pattern excludes, so the advertisement states + * the accepted set without adding a second runtime check. + */ +export const declaredTokenPattern = ( + schema: Schema, + pattern: RegExp, +): Schema => schema.meta({ pattern: declaredPattern(pattern) }); + /** * Check `predicate` and declare it as an `allOf` of patterns built from the * same expressions, annotated with how the declaration relates to it. diff --git a/tests/acceptance/browser/observationDurationCli.test.ts b/tests/acceptance/browser/observationDurationCli.test.ts index 9e32fedf06..f9fb248e4d 100644 --- a/tests/acceptance/browser/observationDurationCli.test.ts +++ b/tests/acceptance/browser/observationDurationCli.test.ts @@ -1,3 +1,4 @@ +import { Ajv2020 } from "ajv/dist/2020.js"; import { expect } from "vitest"; import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js"; import { cliTest } from "../../support/cli/cliFixture.js"; @@ -62,18 +63,23 @@ cliTest( arguments: ["inspect-web-page", "--schema", "--json"], }); expect(result.exitCode).toBe(0); - expect(result.json).toMatchObject({ - options: { - properties: { - observationMs: { - default: 500, - anyOf: [ - { type: "integer", minimum: 0 }, - { type: "string", pattern: "^[0-9]+$" }, - ], - }, - }, - }, + const observationMs = ( + result.json as { + options: { + properties: Record[0]>; + }; + } + ).options.properties.observationMs; + if (observationMs === undefined) + throw new Error("inspect-web-page advertises no observationMs"); + expect(observationMs).toMatchObject({ + default: 500, + anyOf: [{ type: "integer", minimum: 0 }, { type: "string" }], }); + const validate = new Ajv2020({ strict: false }).compile(observationMs); + for (const token of ["0", "0500", "9007199254740991"]) + expect(validate(token), token).toBe(true); + for (const token of ["9007199254740992", "0x10"]) + expect(validate(token), token).toBe(false); }, ); diff --git a/tests/acceptance/webRuntimeCli.test.ts b/tests/acceptance/webRuntimeCli.test.ts index 7945a4bbba..244b0b7b99 100644 --- a/tests/acceptance/webRuntimeCli.test.ts +++ b/tests/acceptance/webRuntimeCli.test.ts @@ -3,6 +3,7 @@ import { once } from "node:events"; import { createServer } from "node:http"; import type { Socket } from "node:net"; import { fileURLToPath } from "node:url"; +import { Ajv2020 } from "ajv/dist/2020.js"; import { promisify } from "node:util"; import { expect, it, onTestFinished } from "vitest"; import { z } from "zod"; @@ -64,23 +65,31 @@ it("advertises the canonical observation duration bounds through the compiled CL [entrypoint, "observe-web-execution", "--schema", "--json"], { env: environment(), timeout: 20_000 }, ); - expect(JSON.parse(stdout)).toMatchObject({ - options: { - properties: { - observationMs: { - default: 10_000, - anyOf: [ - { - type: "integer", - minimum: 1, - maximum: 2_147_483_647, - }, - { type: "string", pattern: "^[0-9]+$" }, - ], - }, + const observationMs = ( + JSON.parse(stdout) as { + options: { + properties: Record[0]>; + }; + } + ).options.properties.observationMs; + if (observationMs === undefined) + throw new Error("observe-web-execution advertises no observationMs"); + expect(observationMs).toMatchObject({ + default: 10_000, + anyOf: [ + { + type: "integer", + minimum: 1, + maximum: 2_147_483_647, }, - }, + { type: "string" }, + ], }); + const validate = new Ajv2020({ strict: false }).compile(observationMs); + for (const token of ["1", "010000", "2147483647"]) + expect(validate(token), token).toBe(true); + for (const token of ["0", "2147483648", "0x10"]) + expect(validate(token), token).toBe(false); }); it("runs the compiled public listener command through its default native CDP composition", async () => { diff --git a/tests/boundary/cli/cliDecimalArguments.test.ts b/tests/boundary/cli/cliDecimalArguments.test.ts index ba7d865721..0baa2e8612 100644 --- a/tests/boundary/cli/cliDecimalArguments.test.ts +++ b/tests/boundary/cli/cliDecimalArguments.test.ts @@ -22,7 +22,9 @@ const numericBranches = (schema: unknown): boolean => { return false; }; -const bounds = (schema: unknown): Array<{ min: number; max: number }> => { +const bounds = ( + schema: unknown, +): Array<{ min: number; max: number; candidate: number }> => { if (!isRecord(schema)) return []; const nested = ["anyOf", "oneOf", "allOf"].flatMap((key) => Array.isArray(schema[key]) ? schema[key].flatMap(bounds) : [], @@ -47,7 +49,7 @@ const bounds = (schema: unknown): Array<{ min: number; max: number }> => { ? schema.default : min; return Number.isSafeInteger(preferred) && preferred >= min && preferred <= max - ? [...nested, { min: preferred, max }] + ? [...nested, { min, max, candidate: preferred }] : nested; }; @@ -147,14 +149,26 @@ describe("decimal integer CLI admission", () => { // Decimal tokens are the only numeric spelling. } } + const range = bounds(item)[0]; const candidate = - bounds(item)[0]?.min ?? + range?.candidate ?? (probed === undefined ? undefined : Number(probed)); if (candidate === undefined) { failures.push(`${label}: no in-range decimal candidate`); continue; } const decimal = String(candidate); + if (range !== undefined) { + for (const value of [range.min - 1, range.max + 1]) { + if (value < 0) continue; + for (const token of [String(value), `000${value}`]) { + if (validate(token)) + failures.push( + `${label}: advertised schema accepts out-of-range ${token}`, + ); + } + } + } try { expect(read(decimal)).toBe(candidate); } catch (error) { @@ -163,7 +177,7 @@ describe("decimal integer CLI admission", () => { ); continue; } - const admitsLeadingZeros = JSON.stringify(item).includes("^[0-9]+$"); + const admitsLeadingZeros = validate(`0${decimal}`); try { const parsed = read(`0${decimal}`); if (parsed !== candidate) @@ -211,36 +225,36 @@ describe("decimal integer CLI advertisement", () => { return JSON.parse(stdout) as unknown; }; - it("publishes the token grammar in --schema for arguments and options", async () => { + it("publishes the token range in --schema for arguments and options", async () => { + const validateToken = (schema: unknown, token: string): boolean => + new Ajv2020({ strict: false }).compile( + schema as Parameters[0], + )(token) === true; const location = await schemaOf("trace-web-source-location"); - expect(location).toMatchObject({ - args: { - properties: { - line: { - description: "One-based generated line", - anyOf: [ - { type: "integer", minimum: 1 }, - { type: "string", pattern: "^[0-9]+$" }, - ], - }, - }, - }, + const line = (location as { args: { properties: { line: unknown } } }).args + .properties.line; + expect(line).toMatchObject({ + description: "One-based generated line", + anyOf: [{ type: "integer", minimum: 1 }, { type: "string" }], }); - expect(await schemaOf("inspect-web-network-capture")).toMatchObject({ - options: { - properties: { - record: { - type: "array", - items: { - anyOf: [ - { type: "integer", minimum: 0 }, - { type: "string", pattern: "^[0-9]+$" }, - ], - }, - }, - }, - }, + for (const token of ["1", "0001"]) + expect(validateToken(line, token), token).toBe(true); + for (const token of ["0", "0000"]) + expect(validateToken(line, token), token).toBe(false); + + const capture = await schemaOf("inspect-web-network-capture"); + const record = ( + capture as { + options: { properties: { record: { items: unknown } } }; + } + ).options.properties.record.items; + expect(record).toMatchObject({ + anyOf: [{ type: "integer", minimum: 0 }, { type: "string" }], }); + for (const token of ["0", "03"]) + expect(validateToken(record, token), token).toBe(true); + expect(validateToken(record, "-1")).toBe(false); + expect(await schemaOf("environment-serve")).toMatchObject({ options: { properties: { diff --git a/tests/boundary/cli/cliDecimalBounds.test.ts b/tests/boundary/cli/cliDecimalBounds.test.ts new file mode 100644 index 0000000000..0e35878c57 --- /dev/null +++ b/tests/boundary/cli/cliDecimalBounds.test.ts @@ -0,0 +1,52 @@ +import { Ajv2020 } from "ajv/dist/2020.js"; +import { expect } from "vitest"; + +import { cliTest } from "../../support/cli/cliFixture.js"; + +cliTest.for([ + { + command: "inspect-sqlite-database", + field: "rowLimit", + flag: "--row-limit", + accepted: ["1", "0001", "9007199254740991"], + rejected: ["0", "0000", "9007199254740992"], + }, + { + command: "inspect-byte-entropy", + field: "blockSize", + flag: "--block-size", + accepted: ["256", "00256", "65536"], + rejected: ["0", "255", "65537", "0065537"], + }, +])( + "advertises and enforces $command decimal bounds", + async (entry, { cli }) => { + const discovery = await cli.run({ + arguments: [entry.command, "--schema", "--format", "json"], + }); + expect(discovery.exitCode).toBe(0); + const schema = JSON.parse(discovery.stdout).options.properties[entry.field]; + const validate = new Ajv2020({ strict: false }).compile(schema); + for (const token of entry.accepted) + expect(validate(token), token).toBe(true); + for (const token of entry.rejected) { + expect(validate(token), token).toBe(false); + const execution = await cli.run({ + arguments: [ + entry.command, + "/nonexistent/decimal-bounds-target", + `${entry.flag}=${token}`, + "--format", + "json", + ], + }); + expect(execution.exitCode).toBe(1); + expect(JSON.parse(execution.stdout)).toMatchObject({ + code: "VALIDATION_ERROR", + fieldErrors: expect.arrayContaining([ + expect.objectContaining({ path: entry.field }), + ]), + }); + } + }, +);