Skip to content

Commit b9509fe

Browse files
thymikeeclaude
andauthored
refactor: extract the .ad script codec into packages/ad-script (#1478) (#1536)
* refactor: extract the .ad script codec into packages/ad-script Moves the mutually-coupled .ad read/write codec (script.ts, script-utils.ts, script-formatting.ts, open-script.ts) plus the target-v1 annotation SERDE slice of target-identity.ts into a new private leaf package, @agent-device/ad-script, exporting only `.`. This is option 1 from the P5 scoping dossier on #1478: the codec is shared by the daemon's session-script publication writer, the future replay engine, the CLI's `replay export`, and Maestro's failure-label formatting, so it can no longer live in root src/ once packages/ad-replay lands (R11 forbids a package reaching into root src), and a second export subpath or writer-half duplication are both ruled out by existing gates/tests. target-identity.ts keeps only the record/replay-shared classification core (classifyTargetBindingMatch, local-identity/ancestry-prefix matching), importing its shared types from the new package. Every real consumer (re-derived by grep, not the dossier's list alone) is rewired to @agent-device/ad-script. Refs #1478 Co-Authored-By: Claude <[email protected]> * refactor: trim the ad-script façade to real consumers, lock the one-export boundary - packages/ad-script/src/index.ts: drop parseReplaySeriesFlags, formatTargetAnnotationCommentLine, parseTargetAnnotationCommentLine, TargetAnnotationLineParseResult, and TargetRect from the public façade — none has a consumer outside the package (re-swept every remaining export by grep; everything else kept has at least one real external importer). The functions/types stay exported from their declaring internal modules for the package's own internal use (script.ts, script-formatting.ts). - scripts/layering/package-boundaries.test.ts: add the parallel R11 assertions "the real tree parses, declares, and passes R11" already makes for maestro/provider-webdriver/provider-limrun/xml — ad-script exports exactly `.`, depends on exactly contracts+kernel, and is declared in root package.json — plus ad-script entries in the deep-resolution rejection coverage. Verified the lock catches a regression: temporarily added a fake `./codec` export to packages/ad-script/package.json and confirmed both the export-key-list assertion and the deep-resolution-rejection assertion fail; removed the plant and reconfirmed green. Refs #1478 Co-Authored-By: Claude <[email protected]> * fix: remove polynomial-redos ambiguity from the target-v1 annotation line regex CodeQL js/polynomial-redos flagged TARGET_ANNOTATION_LINE_RE (packages/ad-script/src/internal/target-annotation-serde.ts): the payload group's `\s+(.*)` let `\s+` and the unconstrained `.*` both match whitespace, so a run of separator whitespace that ultimately fails to complete the match has many `\s+`/`.*` splits to backtrack through before concluding failure. Anchor the payload group on `\S` (the exact complement of `\s`), so the mandatory `\s+` separator and the payload's first character can never overlap — the split point becomes unique and no backtracking is possible. Behavior-preserving: the only caller (parseTargetAnnotationCommentLine) always matches against an already-.trim()-ed line, whose last character (whenever the tag matches at all) is never whitespace — so a payload section `\S.*` would reject (content that is entirely whitespace) can never reach this regex through the real call path. Verified against the frozen replay-compat corpus and the full serde/parser test suites, unmodified. Added a regression test with the exact adversarial shape CodeQL/the reviewer cited (many tab pairs after the version digits), asserting sub-second parse. Refs #1478 Co-Authored-By: Claude <[email protected]> * test(ad-script): pin the annotation-line pattern's linear rejection directly The entry-point adversarial case matched greedily even with the retired regex (trim strips edge whitespace and per-line input carries no newline), so it proved nothing about the pattern. The regression surface is the pattern itself: an interior tab run with an x-newline tail fails the match, which the retired form re-split quadratically (3.7s at 100k tabs) and the \S anchor rejects in one attempt. Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
1 parent 26246ea commit b9509fe

63 files changed

Lines changed: 1060 additions & 840 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@
145145
"check:unit": "pnpm check:contention-retry && pnpm test:unit && pnpm test:smoke",
146146
"check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
147147
"prepack": "pnpm check:mcp-metadata && pnpm package:npm",
148-
"typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
148+
"typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/ad-script packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
149149
"test-app:install": "pnpm install --dir examples/test-app",
150150
"test-app:start": "pnpm --dir examples/test-app start",
151151
"test-app:ios": "pnpm --dir examples/test-app ios",
@@ -245,6 +245,7 @@
245245
"yaml": "^2.9.0"
246246
},
247247
"devDependencies": {
248+
"@agent-device/ad-script": "workspace:*",
248249
"@agent-device/contracts": "workspace:*",
249250
"@agent-device/kernel": "workspace:*",
250251
"@agent-device/maestro": "workspace:*",

‎packages/ad-script/package.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "@agent-device/ad-script",
3+
"version": "0.0.0",
4+
"private": true,
5+
"sideEffects": false,
6+
"type": "module",
7+
"description": "Private canonical .ad replay script codec (read + write) for agent-device.",
8+
"dependencies": {
9+
"@agent-device/contracts": "workspace:*",
10+
"@agent-device/kernel": "workspace:*"
11+
},
12+
"exports": {
13+
".": {
14+
"types": "./src/index.ts",
15+
"default": "./src/index.ts"
16+
}
17+
}
18+
}

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/**
2+
* The `.ad` script codec façade (#1478 P5 scoping dossier, "the codec seam").
3+
*
4+
* The canonical `.ad` replay script format — read half (parsing a script into
5+
* actions) and write half (formatting actions back into script lines) of one
6+
* artifact, mutually coupled (`script-formatting.ts` calls into the `open`
7+
* action's writer; `script.ts` calls into its parser). Shared by the daemon's
8+
* session-script publication writer, the replay engine's script reader, the
9+
* CLI's `replay export`, and Maestro's failure-label formatting.
10+
*
11+
* Also owns the `# agent-device:target-v1` annotation SERDE (wire type,
12+
* canonical field order, normalization, size caps, payload parsing). The
13+
* companion classification core (`classifyTargetBindingMatch`, local-identity
14+
* + ancestry-prefix matching) is NOT part of this codec — it stays in
15+
* `src/replay/target-identity.ts`, which imports the types below.
16+
*/
17+
18+
export {
19+
parseReplayScriptDetailed,
20+
readReplayScriptMetadata,
21+
REPLAY_VAR_KEY_RE,
22+
} from './internal/script.ts';
23+
export type { ParsedReplayScript, ReplayScriptMetadata } from './internal/script.ts';
24+
25+
export {
26+
appendScriptSeriesFlags,
27+
formatDivergenceActionLabel,
28+
formatScriptArg,
29+
formatScriptStringLiteral,
30+
isClickLikeCommand,
31+
isTouchTargetCommand,
32+
stripRecordedRefGeneration,
33+
} from './internal/script-utils.ts';
34+
35+
export {
36+
formatPortableActionLine,
37+
formatTargetAnnotationLines,
38+
} from './internal/script-formatting.ts';
39+
40+
export {
41+
normalizeIdentifierField,
42+
normalizeLabelField,
43+
normalizeRoleField,
44+
parseTargetAnnotationV1Payload,
45+
serializeTargetAnnotationV1,
46+
truncateToUtf8Bytes,
47+
utf8ByteLength,
48+
TARGET_ANNOTATION_MAX_ANCESTRY,
49+
TARGET_ANNOTATION_MAX_FIELD_BYTES,
50+
TARGET_ANNOTATION_MAX_PAYLOAD_BYTES,
51+
} from './internal/target-annotation-serde.ts';
52+
export type {
53+
TargetAncestryEntry,
54+
TargetAnnotationV1,
55+
TargetScrollRegion,
56+
TargetVerification,
57+
} from './internal/target-annotation-serde.ts';

src/replay/__tests__/script.test.ts renamed to packages/ad-script/src/internal/__tests__/script.test.ts

Lines changed: 8 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
1-
import fc from 'fast-check';
21
import { test } from 'vitest';
32
import assert from 'node:assert/strict';
4-
import { PROPERTY_RUNS, replayScriptArb } from '../../__tests__/test-utils/index.ts';
53
import { AppError } from '@agent-device/kernel/errors';
64
import {
75
parseReplayScriptDetailed,
86
readReplayScriptMetadata,
97
REPLAY_METADATA_PLATFORMS,
108
} from '../script.ts';
119
import { formatPortableActionLine, formatTargetAnnotationLines } from '../script-formatting.ts';
12-
import type { TargetAnnotationV1 } from '../target-identity.ts';
10+
import type { TargetAnnotationV1 } from '../target-annotation-serde.ts';
1311
import type { SessionAction } from '@agent-device/contracts/session';
1412

1513
// `writeReplayScript` (the `--update` heal-and-rewrite serializer) was
@@ -624,24 +622,10 @@ test('formatDivergenceActionLabel categorically drops fill/type text but keeps t
624622
);
625623
});
626624

627-
// Property, not another example: `.ad` scripts are written by hand, recorded,
628-
// and rewritten, so the parser and the line formatter must agree on ONE
629-
// canonical form — re-serializing a parsed script has to be a fixed point.
630-
// Generated lines come from the shared `.ad` generator, so a new command shape
631-
// extends the generator rather than adding another pinned script here.
632-
test('serializing a parsed script is a fixed point for generated scripts', () => {
633-
fc.assert(
634-
fc.property(replayScriptArb, (script) => {
635-
const parsed = parseReplayScriptDetailed(script).actions;
636-
const canonical = formatReplayScriptForTest(parsed);
637-
const reparsed = parseReplayScriptDetailed(canonical).actions;
638-
assert.equal(formatReplayScriptForTest(reparsed), canonical);
639-
// The action identity survives the rewrite: same commands, same targets.
640-
assert.deepEqual(
641-
reparsed.map((action) => [action.command, action.positionals]),
642-
parsed.map((action) => [action.command, action.positionals]),
643-
);
644-
}),
645-
{ numRuns: PROPERTY_RUNS },
646-
);
647-
});
625+
// The property test asserting "serializing a parsed script is a fixed point
626+
// for generated scripts" stays at `src/replay/__tests__/ad-script-round-trip.test.ts`:
627+
// its script generator (`replayScriptArb`) is derived from the root command
628+
// catalog and selector grammar (`src/__tests__/test-utils/property-arbitraries.ts`),
629+
// which this package cannot import without an R11 package→root-src escape
630+
// (#1478 P5 scoping dossier §5d). It exercises this package's exports via
631+
// the `@agent-device/ad-script` specifier instead of duplicating the codec.

0 commit comments

Comments
 (0)