Skip to content

Commit 9a4b41e

Browse files
committed
fix(ad-script): address review — strict shell parity for single quotes, pinned grammar rules
Single-quoted script values now decode exactly what the shell hands over: the only escape is `\'` (the one deliberate extension, since a shell's single quotes cannot carry an apostrophe and a `label="don't"` selector has to be writable in a script), and a backslash keeps its own character instead of collapsing. - The tokenizer comment states the scoped guarantee: a whole-word quoted run gains the shell reading (that is the change), a run the shell would not read as one argument keeps its old bare meaning. - The admission test now asserts every script token is a long `--` spelling, so an `-d`/`-s` regression fails there. - The `wait` long-form-only comment carries the real trade: writer parity, and realistic short-flag-waited-text versus an almost-impossible literal that quoting already solves. - Docs: script flags are declared-and-recorded ones (no contradiction with the scroll pixel note), single-quote decode rules match the code, and the discovery counts sentence is scoped to the no-match error as it actually behaves.
1 parent 31eb324 commit 9a4b41e

6 files changed

Lines changed: 40 additions & 30 deletions

File tree

‎packages/ad-script/src/internal/__tests__/script.test.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -350,7 +350,20 @@ test('an unclosed single quote never turns a previously valid line into an error
350350
assert.deepEqual(parsed[0]?.positionals, ['text', "don't"]);
351351
});
352352

353-
test("apostrophes that survive decoding keep the bare reading, not the shell's split", () => {
353+
test("single quotes carry an apostrophe through ', and a backslash stays itself", () => {
354+
// Shell parity: `agent-device wait 'label="don\'t"'` hands over the backslash-
355+
// apostrophe pair, so the script has to read the same selector. A shell keeps a
356+
// bare `\` inside single quotes, and so does the script line.
357+
const parsed = parseReplayScriptDetailed(
358+
[String.raw`wait 'label="don\'t"'`, String.raw`snapshot --scope 'root\.section'`].join('\n') +
359+
'\n',
360+
).actions;
361+
362+
assert.deepEqual(parsed[0]?.positionals, ['label="don\'t"']);
363+
assert.equal(parsed[1]?.flags.snapshotScope, String.raw`root\.section`);
364+
});
365+
366+
test('apostrophes that survive decoding keep the old bare reading', () => {
354367
// The shell reads `'don't do this'` as three arguments. A script line has no
355368
// second reader to hand it to, so re-tokenizing would change what a
356369
// previously-valid line means; it stays one bare token run, as it always was.

‎packages/ad-script/src/internal/script-utils.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,9 +75,11 @@ const SCROLL_SCRIPT_FLAG_MAP = new Map<string, ScriptFlagEntry>([
7575
* (`SELECTOR_SNAPSHOT_FLAGS`) and they are recorded, so the script grammar
7676
* recognizes them too. Otherwise they land inside the positional list and the
7777
* wait parser refuses the line as selector-shaped text. Long spellings only:
78-
* the `-d`/`-s` CLI aliases would reclassify pre-existing positional data
79-
* (`wait text -s so funny` once meant the text `-s so funny`), and the writer
80-
* only ever emits the long form.
78+
* this is the spelling the writer emits for `wait`, so nothing the recorder can
79+
* write needs an alias, and matching `-d`/`-s` would reclassify realistic
80+
* waited text (`wait text -s so funny`) to buy almost nothing — the only line
81+
* losing its old reading is one whose whole token is a literal long flag word,
82+
* which a hand-written script can spell with the selector wrapped instead.
8183
*/
8284
const WAIT_SCRIPT_FLAG_MAP = new Map<string, ScriptFlagEntry>([
8385
['--raw', { key: 'snapshotRaw', kind: 'boolean' }],

‎packages/ad-script/src/internal/script.ts‎

Lines changed: 11 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -557,11 +557,15 @@ function readQuotedReplayToken(
557557
* A single-quoted token: `'id="far-button"'` or `'label="Sign in"'` (#3197). The
558558
* shell's single quotes strip to one argument and keep `"` literal; a hand-written
559559
* `.ad` line is the same text, so the tokenizer must agree or the identical command
560-
* parses at the CLI and fails in a script. The candidate must close immediately
561-
* before whitespace or end of line: a quote that stops mid-word was punctuation in
562-
* the old bare reading (`wait text it's fine`, `'don't do this'`), so the whole run
563-
* keeps its old meaning and nothing that parsed before changes meaning. Inside the
564-
* quotes only `\'` and `\\` escape.
560+
* parses at the CLI and fails in a script. The guarantee is scoped: a run the shell
561+
* reads as one quoted argument NOW reads as one argument (`'Sign in'` was two bare
562+
* tokens before, and taking the shell reading is the point), while a run it would
563+
* not — an unclosed quote or a quote that stops mid-word (`wait text it's fine`,
564+
* `'don't do this'`) — keeps its old bare meaning, so no line relied on before this
565+
* change is re-tokenized. Inside the quotes only `\'` escapes, as in the shell, where
566+
* a `\` keeps its own character; `\'` itself is the one deliberate extension, because
567+
* a shell's single quotes carry no apostrophe at all and a selector like
568+
* `label="don't"` has to be writable in a script without JSON double quotes.
565569
*/
566570
function readSingleQuotedReplayToken(
567571
line: string,
@@ -571,7 +575,7 @@ function readSingleQuotedReplayToken(
571575
let end = cursor + 1;
572576
while (end < line.length) {
573577
const char = line.charAt(end);
574-
if (char === '\\') {
578+
if (char === '\\' && line.charAt(end + 1) === "'") {
575579
end += 2;
576580
continue;
577581
}
@@ -590,19 +594,7 @@ function isReplayTokenBoundary(line: string, index: number): boolean {
590594
}
591595

592596
function decodeSingleQuotedReplayLiteral(value: string): string {
593-
let decoded = '';
594-
let cursor = 0;
595-
while (cursor < value.length) {
596-
const char = value.charAt(cursor);
597-
if (char === '\\' && (value.charAt(cursor + 1) === "'" || value.charAt(cursor + 1) === '\\')) {
598-
decoded += value.charAt(cursor + 1);
599-
cursor += 2;
600-
continue;
601-
}
602-
decoded += char;
603-
cursor += 1;
604-
}
605-
return decoded;
597+
return value.replaceAll(String.raw`\'`, "'");
606598
}
607599

608600
function readBareReplayToken(line: string, cursor: number): { value: string; nextCursor: number } {

‎src/commands/replay/script-flag-admission.test.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,12 @@ describe.each(SCRIPT_FLAG_COMMANDS)('%s script flags', (command) => {
5151
});
5252

5353
test('every script token matches the declaration spelling and kind exactly', () => {
54-
// The long spelling only: an alias the grammar invented that the CLI does not
55-
// declare would parse a line `agent-device <command>` itself would refuse.
54+
// Long spelling only, and only a spelling the CLI itself declares: a short
55+
// alias invented here would parse a line the recording never writes, and a
56+
// single-letter token would reclassify positional data the grammar used to
57+
// leave alone.
5658
for (const entry of entries) {
59+
expect(entry.token.startsWith('--')).toBe(true);
5760
const definitions = getFlagDefinitionsForKey(entry.key as never);
5861
const declaredNames = new Set(definitions.flatMap((definition) => [...definition.names]));
5962
expect(declaredNames.has(entry.token)).toBe(true);

‎src/commands/schema/cli-help.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ Script paths are the caller's:
164164
test --json marks a failed test with infrastructure: true only when the owning runtime classified a device, runner, boot, or transport failure. It remains a failed test; consumers may use the tag to distinguish "the oracle did not run" from a behavioral replay divergence without weakening either gate.
165165
166166
Script line grammar:
167-
A .ad line is <command> [positional...] [flag...]. Whitespace splits tokens; a token quoted with " or ' is one argument, and single quotes keep a double quote literal, exactly as at the shell (press 'id="far"' is one selector). Values in double quotes are JSON strings (escape \\\\, \\", \\t, \\n); values in single quotes are literal except for \\' and \\\\. A command reads only its own declared flags, so the CLI form and the script line are the same text: scroll down --until 'id="x"', wait 'label="Sign in"' --raw, snapshot -i. Recorded lines carry what the flag declaration marks recorded; per-request options (--settle, --verify) are not part of a step and are not written.
167+
A .ad line is <command> [positional...] [flag...]. Whitespace splits tokens; a token quoted with " or ' is one argument, and single quotes keep a double quote literal, exactly as at the shell (press 'id="far"' is one selector). Values in double quotes are JSON strings (escape \\\\, \\", \\t, \\n). Values in single quotes are literal, as at the shell: a backslash keeps its own character and the only escape is \\' for an apostrophe. A script carries only the flags declared for that command and marked recorded, so the script form of a step matches the CLI form: scroll down --until 'id="x"', wait 'label="Sign in"' --raw. CLI-only spellings and per-request options are not part of a step: --settle, --verify, scroll --pixels/--duration-ms, and the device-selection flags (--platform, --serial, --device) are the common ones a script does not carry.
168168
Reaching an off-screen target is viewport-independent in a script the same way it is at the CLI: write scroll down --until <selector>, not a fixed scroll amount that passes on one screen size and fails on another.
169169
170170
Reusable open-to-destination scripts:

‎website/docs/docs/replay-e2e.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,8 @@ close
5353
```
5454

5555
- A token quoted with `"` or `'` is one argument. Single quotes keep a `"` literal, so `'id="far-button"'` and `"id=\"far-button\""` are the same selector — write whichever matches how you typed the command at the shell.
56-
- Values in double quotes are JSON strings, so escape `\\`, `\"`, `\t`, and `\n`. Values in single quotes are literal except for `\'` and `\\`.
57-
- A command accepts only its own flags. A flag the CLI accepts is available in a script when it belongs to the step; per-request options are not part of a step. `--settle`, `--verify`, and the device-selection flags (`--platform`, `--serial`, `--device`) are the common ones a script does not carry.
56+
- Values in double quotes are JSON strings, so escape `\\`, `\"`, `\t`, and `\n`. Values in single quotes are literal, as at the shell: a backslash keeps its own character, and the only escape is `\'` for an apostrophe.
57+
- A script carries only the flags declared for that command and marked recorded; CLI-only spellings and per-request options are not part of a step. `--settle`, `--verify`, `scroll --pixels`/`--duration-ms`, and the device-selection flags (`--platform`, `--serial`, `--device`) are the common ones a script does not carry.
5858
- `help <command>` prints the flags each command accepts. `help scripting` prints this grammar.
5959

6060
Reaching an off-screen element is viewport-independent in a script exactly as it is at the CLI. Prefer the stop condition over a fixed amount, which passes on one screen size and fails on another:
@@ -68,7 +68,7 @@ scroll down 0.8
6868
scroll bottom
6969
```
7070

71-
A `#` only starts a comment at the beginning of a line. A scroll line carries `--until` and keeps its distance as a positional; `--pixels` and `--duration-ms` belong to the CLI invocation, not to a step. `wait` carries `--raw`, `--depth <n>`, and `--scope <selector|@ref>` to choose the capture its target is read from.
71+
A `#` only starts a comment at the beginning of a line. A scroll line carries `--until` and keeps its distance as a positional (`scroll down 0.8 --until <selector>`). `wait` carries `--raw`, `--depth <n>`, and `--scope <selector|@ref>` (long spellings; the `-d`/`-s` CLI aliases stay out of scripts so a hand-written line like `wait text -s so funny` keeps meaning its literal text) to choose the capture its target is read from.
7272

7373
## Run replay
7474

@@ -160,7 +160,7 @@ agent-device test ./workflows --reporter default --reporter junit:./tmp/junit.xm
160160
- `test` discovers `.ad` files from files, directories, or globs and runs them serially.
161161
- Quote relative globs to expand them on the caller from its working directory, including when the directory name contains glob characters such as `[` or `{`. A missing file input without glob characters reports an error.
162162
- `context platform=...` inside each `.ad` file is the target source of truth for suite execution.
163-
- `--platform` is a filter for suite discovery; files without platform metadata are skipped when a filter is present, and the run reports how many sources were skipped for having no `context platform=` header versus how many declared another platform. Add the header to run a file under a filter, or omit `--platform` and let the selected device decide.
163+
- `--platform` is a filter for suite discovery; files without platform metadata are skipped when a filter is present. When filtering leaves no runnable sources, the no-match error reports how many sources were skipped for having no `context platform=` header versus how many declared another platform. Add the header to run a file under a filter, or omit `--platform` and let the selected device decide.
164164
- `context timeout=...` and `context retries=...` can be declared per script; CLI flags override metadata. Retries are capped at `3`, and duplicate keys in the context header fail fast instead of silently overriding each other.
165165
- By default, suite artifacts are written under `.agent-device/test-artifacts/<run-id>/...`. Each attempt writes `replay.ad`, `result.txt`, and `replay-timing.ndjson`. Failed attempts also keep copied logs and artifact files when the replay produced them.
166166
- Copied diagnostic artifacts receive numbered filenames when their names collide with another artifact, a replay source, timing trace, or attempt manifest. `result.txt` lists the retained names in `copiedArtifacts`.

0 commit comments

Comments
 (0)