Skip to content

Commit 60400d0

Browse files
authored
feat(mutation): add target-annotation-serde + snapshot-occlusion kernels (#1553)
* feat(mutation): add target-annotation-serde + snapshot-occlusion kernels Both are pure decision kernels the lane's own membership rule covers (target-annotation-serde: parse/validate/normalize the .ad comment-line codec, zero I/O; snapshot-occlusion: pure covered/not-covered decision where a wrong answer silently blocks or mis-allows a tap) but were excluded from KERNEL_MODULES. Fixing the harness's packages/*/src blind spot was required, not optional: test-scope.ts, ownership.ts, and vitest.mutation.config.ts all hardcoded `src/` as the only place a kernel's tests could live. target-annotation-serde's own tests live under packages/ad-script/src/internal/__tests__/, so without this fix the module would score 0% from day one — not from weak tests, but because its test file was silently invisible to the lane. Widened the same three places, plus mutation-affected.yml's path filter and isTestFile/ownedTestFiles in ownership.ts, to also recognize packages/*/src/**/*.test.ts (mirroring vitest.config.ts's own unit-core project include list). Triaged every surviving mutant from the initial run: real coverage gaps got a new/adjusted test (kill-with-test), everything else is documented equivalent with an inline comment at the mutation site explaining the invariant that makes it unobservable (redundant early-returns, JSON.stringify dropping undefined-valued keys, Number.isFinite/isSafeInteger's total-function safety, caller-enforced positiveRect/candidate invariants, etc). Baseline recorded from the actual measured run, not inherited or guessed: 94.03% (315/335) and 89.74% (175/195). * style: run the formatter over the four files the gate flagged
1 parent e5cebcd commit 60400d0

13 files changed

Lines changed: 872 additions & 42 deletions

File tree

‎.github/workflows/mutation-affected.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,19 @@ name: Mutation Affected
2222
on:
2323
pull_request:
2424
paths:
25-
# Kernel sources, every src test (ownership is derived, so any test may own
26-
# a kernel — `select` decides, not this filter), and the lane's own tooling.
27-
# scripts/mutation/workflow.test.ts asserts this covers the registry.
25+
# Kernel sources, every src/package test (ownership is derived, so any
26+
# test may own a kernel — `select` decides, not this filter), and the
27+
# lane's own tooling. scripts/mutation/workflow.test.ts asserts this
28+
# covers the registry.
2829
- 'packages/kernel/src/errors.ts'
2930
- 'src/daemon/ref-frame.ts'
3031
- 'src/commands/interaction/runtime/settle.ts'
3132
- 'src/utils/scroll-edge-state.ts'
3233
- 'src/selectors/**'
34+
- 'packages/ad-script/src/internal/target-annotation-serde.ts'
35+
- 'src/snapshot/snapshot-occlusion.ts'
3336
- 'src/**/*.test.ts'
37+
- 'packages/*/src/**/*.test.ts'
3438
- 'scripts/mutation/**'
3539
- 'scripts/lib/**'
3640
- 'stryker.config.json'

‎.github/workflows/mutation-weekly.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ jobs:
5252
- { name: selectors-2, module: selectors, shard: 2/4 }
5353
- { name: selectors-3, module: selectors, shard: 3/4 }
5454
- { name: selectors-4, module: selectors, shard: 4/4 }
55+
- { name: target-annotation-serde, module: target-annotation-serde }
56+
- { name: snapshot-occlusion, module: snapshot-occlusion }
5557
steps:
5658
- name: Checkout
5759
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -109,7 +111,7 @@ jobs:
109111
# runner exports it, so the summary and the artifact carry the same numbers.
110112
- name: Ratchet the merged sweep and propose the next baseline
111113
run: |
112-
pnpm mutation:check --report-dir .tmp/mutation/shards --expect-shards 8 --update
114+
pnpm mutation:check --report-dir .tmp/mutation/shards --expect-shards 10 --update
113115
cp mutation-baselines/decision-kernels.json .tmp/mutation/proposed-baseline.json
114116
git checkout -- mutation-baselines/decision-kernels.json
115117

‎mutation-baselines/decision-kernels.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,24 @@
4848
"strykerVersion": "9.6.1",
4949
"configHash": "sha256:806d9f2e657f",
5050
"updatedAt": "2026-07-27T14:29:40.750Z"
51+
},
52+
"target-annotation-serde": {
53+
"score": 94.03,
54+
"killed": 315,
55+
"survived": 20,
56+
"total": 335,
57+
"strykerVersion": "9.6.1",
58+
"configHash": "sha256:8b633048f754",
59+
"updatedAt": "2026-08-02T07:28:56.278Z"
60+
},
61+
"snapshot-occlusion": {
62+
"score": 89.74,
63+
"killed": 175,
64+
"survived": 20,
65+
"total": 195,
66+
"strykerVersion": "9.6.1",
67+
"configHash": "sha256:8b633048f754",
68+
"updatedAt": "2026-08-02T07:28:56.278Z"
5169
}
5270
}
5371
}

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

Lines changed: 257 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,17 @@ test('a line that merely mentions the tag in prose is an ordinary comment', () =
103103
assert.deepEqual(parseTargetAnnotationCommentLine('# just a comment'), { kind: 'none' });
104104
});
105105

106+
test('a line that is not a comment at all is not a target annotation', () => {
107+
assert.deepEqual(parseTargetAnnotationCommentLine('const x = 1;'), { kind: 'none' });
108+
});
109+
110+
test('leading and trailing whitespace around the annotation line does not break parsing', () => {
111+
const result = parseTargetAnnotationCommentLine(
112+
' # agent-device:target-v1 {"role":"button","verification":"verified"} ',
113+
);
114+
assert.equal(result.kind, 'v1');
115+
});
116+
106117
// ---------------------------------------------------------------------------
107118
// Normalization: NFC, label trim/collapse, normalized-role source
108119
// ---------------------------------------------------------------------------
@@ -117,6 +128,27 @@ test('normalizeLabelField treats a whitespace-only label as absent', () => {
117128
assert.equal(normalizeLabelField(' '), undefined);
118129
});
119130

131+
test('an empty-string id is treated as absent, like a whitespace-only label', () => {
132+
const parsed = parseTargetAnnotationV1Payload(
133+
JSON.stringify({ id: '', role: 'button', verification: 'verified' }),
134+
);
135+
assert.equal(parsed.id, undefined);
136+
});
137+
138+
test('scrollRegion.label serializes and round trips like every other label field', () => {
139+
const evidence = baseEvidence({
140+
id: undefined,
141+
label: undefined,
142+
scrollRegion: { role: 'scrollview', id: 'editor-scroll', label: 'Body' },
143+
});
144+
const json = serializeTargetAnnotationV1(evidence);
145+
assert.ok(
146+
json.includes('"scrollRegion":{"role":"scrollview","id":"editor-scroll","label":"Body"}'),
147+
);
148+
const parsed = parseTargetAnnotationV1Payload(json);
149+
assert.equal(parsed.scrollRegion?.label, 'Body');
150+
});
151+
120152
test('embedded quotes and backslashes in labels round trip losslessly', () => {
121153
const evidence = baseEvidence({ label: 'Say "hi" \\ backslash', id: undefined });
122154
const json = serializeTargetAnnotationV1(evidence);
@@ -200,6 +232,38 @@ test('parser rejects more than 8 ancestry entries', () => {
200232
);
201233
});
202234

235+
test('parser accepts a payload landing exactly on the 4 KiB cap boundary', () => {
236+
// A fixed filler length below the field cap on every other string field,
237+
// plus one tunable ancestry-entry role (also within its own 256-byte field
238+
// cap) sized by exact arithmetic — every character is ASCII, so 1 char is 1
239+
// UTF-8 byte, and the tunable field's required length is computable
240+
// directly rather than searched for.
241+
const FILLER = 'x'.repeat(180);
242+
const build = (padLength: number) => {
243+
const ancestry = Array.from({ length: TARGET_ANNOTATION_MAX_ANCESTRY }, (_unused, index) => ({
244+
role: index === 0 ? 'x'.repeat(padLength) : FILLER,
245+
label: index === 0 ? undefined : FILLER,
246+
}));
247+
return JSON.stringify({
248+
id: FILLER,
249+
role: FILLER,
250+
label: FILLER,
251+
ancestry,
252+
scrollRegion: { role: FILLER, id: FILLER, label: FILLER },
253+
verification: 'verified',
254+
});
255+
};
256+
const base = Buffer.byteLength(build(0), 'utf8');
257+
const padLength = TARGET_ANNOTATION_MAX_PAYLOAD_BYTES - base;
258+
assert.ok(
259+
padLength >= 0 && padLength <= TARGET_ANNOTATION_MAX_FIELD_BYTES,
260+
`fixture no longer straddles the cap (base ${base}, needs pad ${padLength})`,
261+
);
262+
const json = build(padLength);
263+
assert.equal(Buffer.byteLength(json, 'utf8'), TARGET_ANNOTATION_MAX_PAYLOAD_BYTES);
264+
assert.doesNotThrow(() => parseTargetAnnotationV1Payload(json));
265+
});
266+
203267
test('truncateToUtf8Bytes never splits a surrogate pair', () => {
204268
const emoji = '\u{1F600}'; // 4 UTF-8 bytes, a surrogate pair in UTF-16
205269
const truncated = truncateToUtf8Bytes(`ab${emoji}`, 3);
@@ -210,6 +274,27 @@ test('truncateToUtf8Bytes never splits a surrogate pair', () => {
210274
assert.equal(/[\ud800-\udbff]$/.test(truncated), false);
211275
});
212276

277+
test('truncateToUtf8Bytes drops a lone high surrogate at either end of its range', () => {
278+
// Codepoint 0x10000 encodes to the lowest high surrogate (0xD800); 0x10FFFF
279+
// (the last valid Unicode codepoint) encodes to the highest (0xDBFF). Both
280+
// bound cases must trigger the drop, not just a value in the middle of the
281+
// range.
282+
for (const codepoint of [0x10000, 0x10ffff]) {
283+
const astral = String.fromCodePoint(codepoint);
284+
const truncated = truncateToUtf8Bytes(`a${astral}`, 4);
285+
assert.equal(truncated, 'a', `codepoint 0x${codepoint.toString(16)} left a lone surrogate`);
286+
}
287+
});
288+
289+
test('truncateToUtf8Bytes keeps a fully-paired surrogate that lands exactly on the byte budget', () => {
290+
// The budget lands the cut right after a complete surrogate pair (trimming
291+
// only the unrelated trailing "cd"), so nothing here is a split — the
292+
// dangling-high-surrogate guard must NOT also fire on the pair's low half.
293+
const astral = String.fromCodePoint(0x10000);
294+
const truncated = truncateToUtf8Bytes(`ab${astral}cd`, 6);
295+
assert.equal(truncated, `ab${astral}`);
296+
});
297+
213298
// ---------------------------------------------------------------------------
214299
// Malformed / unbound annotations
215300
// ---------------------------------------------------------------------------
@@ -219,33 +304,190 @@ test('parser rejects non-JSON payloads', () => {
219304
});
220305

221306
test('parser rejects a JSON array or scalar payload', () => {
222-
assertInvalidArgs(() => parseTargetAnnotationV1Payload('[]'));
223-
assertInvalidArgs(() => parseTargetAnnotationV1Payload('"button"'));
307+
assertInvalidArgs(() => parseTargetAnnotationV1Payload('[]'), /must be a JSON object/);
308+
assertInvalidArgs(() => parseTargetAnnotationV1Payload('"button"'), /must be a JSON object/);
309+
});
310+
311+
// `typeof null === 'object'` in JS, so a bare `null` payload passes the
312+
// typeof check above and needs its own explicit rejection — the array/scalar
313+
// test above cannot exercise this branch.
314+
test('parser rejects a null payload', () => {
315+
assertInvalidArgs(() => parseTargetAnnotationV1Payload('null'), /must be a JSON object/);
224316
});
225317

226318
test('parser rejects a wrong-typed known field', () => {
227-
assertInvalidArgs(() =>
228-
parseTargetAnnotationV1Payload(JSON.stringify({ role: 42, verification: 'verified' })),
319+
assertInvalidArgs(
320+
() => parseTargetAnnotationV1Payload(JSON.stringify({ role: 42, verification: 'verified' })),
321+
/"role" must be a string/,
322+
);
323+
});
324+
325+
test('parser rejects wrong-typed optional id and label fields, naming each in the message', () => {
326+
assertInvalidArgs(
327+
() =>
328+
parseTargetAnnotationV1Payload(
329+
JSON.stringify({ id: 42, role: 'button', verification: 'verified' }),
330+
),
331+
/"id" must be a string/,
332+
);
333+
assertInvalidArgs(
334+
() =>
335+
parseTargetAnnotationV1Payload(
336+
JSON.stringify({ role: 'button', label: 42, verification: 'verified' }),
337+
),
338+
/"label" must be a string/,
339+
);
340+
});
341+
342+
test('parser rejects ancestry that is not an array', () => {
343+
assertInvalidArgs(
344+
() =>
345+
parseTargetAnnotationV1Payload(
346+
JSON.stringify({ role: 'button', ancestry: 'toolbar', verification: 'verified' }),
347+
),
348+
/"ancestry" must be an array/,
349+
);
350+
});
351+
352+
test('parser rejects an ancestry entry that is not an object', () => {
353+
assertInvalidArgs(
354+
() =>
355+
parseTargetAnnotationV1Payload(
356+
JSON.stringify({ role: 'button', ancestry: ['toolbar'], verification: 'verified' }),
357+
),
358+
/"ancestry\[0\]" must be an object/,
359+
);
360+
assertInvalidArgs(
361+
() =>
362+
parseTargetAnnotationV1Payload(
363+
JSON.stringify({ role: 'button', ancestry: [null], verification: 'verified' }),
364+
),
365+
/"ancestry\[0\]" must be an object/,
366+
);
367+
});
368+
369+
test('parser rejects a scrollRegion or rect that is not an object', () => {
370+
assertInvalidArgs(
371+
() =>
372+
parseTargetAnnotationV1Payload(
373+
JSON.stringify({ role: 'button', scrollRegion: 'list', verification: 'verified' }),
374+
),
375+
/"scrollRegion" must be an object/,
376+
);
377+
assertInvalidArgs(
378+
() =>
379+
parseTargetAnnotationV1Payload(
380+
JSON.stringify({ role: 'button', rect: 'somewhere', verification: 'verified' }),
381+
),
382+
/"rect" must be an object/,
383+
);
384+
});
385+
386+
// `typeof null === 'object'`, so a null scrollRegion/rect needs its own
387+
// explicit rejection — same trap as the top-level null-payload case above.
388+
// Getting this wrong crashes on `null.role`/`null.x` (a raw TypeError)
389+
// instead of a graceful AppError, unlike the string-typed case above.
390+
test('parser rejects a null scrollRegion or rect with AppError, not a native crash on null property access', () => {
391+
assertInvalidArgs(
392+
() =>
393+
parseTargetAnnotationV1Payload(
394+
JSON.stringify({ role: 'button', scrollRegion: null, verification: 'verified' }),
395+
),
396+
/"scrollRegion" must be an object/,
397+
);
398+
assertInvalidArgs(
399+
() =>
400+
parseTargetAnnotationV1Payload(
401+
JSON.stringify({ role: 'button', rect: null, verification: 'verified' }),
402+
),
403+
/"rect" must be an object/,
229404
);
230405
});
231406

232407
test('parser rejects an invalid verification value', () => {
233-
assertInvalidArgs(() =>
234-
parseTargetAnnotationV1Payload(JSON.stringify({ role: 'button', verification: 'maybe' })),
408+
assertInvalidArgs(
409+
() => parseTargetAnnotationV1Payload(JSON.stringify({ role: 'button', verification: 'maybe' })),
410+
/"verification" must be "verified" or "unverifiable"/,
235411
);
236412
});
237413

238-
test('parser rejects a negative or non-integer sibling/viewportOrder', () => {
239-
assertInvalidArgs(() =>
240-
parseTargetAnnotationV1Payload(
241-
JSON.stringify({ role: 'button', sibling: -1, verification: 'verified' }),
242-
),
414+
test('parser rejects a negative or non-integer sibling/viewportOrder, naming each in the message', () => {
415+
assertInvalidArgs(
416+
() =>
417+
parseTargetAnnotationV1Payload(
418+
JSON.stringify({ role: 'button', sibling: -1, verification: 'verified' }),
419+
),
420+
/"sibling" must be a non-negative integer/,
243421
);
244-
assertInvalidArgs(() =>
245-
parseTargetAnnotationV1Payload(
246-
JSON.stringify({ role: 'button', viewportOrder: 1.5, verification: 'verified' }),
247-
),
422+
assertInvalidArgs(
423+
() =>
424+
parseTargetAnnotationV1Payload(
425+
JSON.stringify({ role: 'button', viewportOrder: 1.5, verification: 'verified' }),
426+
),
427+
/"viewportOrder" must be a non-negative integer/,
428+
);
429+
});
430+
431+
test('parser rejects a wrong-typed scrollRegion.id and scrollRegion.label, naming each in the message', () => {
432+
assertInvalidArgs(
433+
() =>
434+
parseTargetAnnotationV1Payload(
435+
JSON.stringify({
436+
role: 'button',
437+
scrollRegion: { role: 'list', id: 42 },
438+
verification: 'verified',
439+
}),
440+
),
441+
/"id" must be a string/,
442+
);
443+
assertInvalidArgs(
444+
() =>
445+
parseTargetAnnotationV1Payload(
446+
JSON.stringify({
447+
role: 'button',
448+
scrollRegion: { role: 'list', label: 42 },
449+
verification: 'verified',
450+
}),
451+
),
452+
/"scrollRegion\.label" must be a string/,
453+
);
454+
});
455+
456+
test('parser rejects a wrong-typed ancestry entry label, naming it in the message', () => {
457+
assertInvalidArgs(
458+
() =>
459+
parseTargetAnnotationV1Payload(
460+
JSON.stringify({
461+
role: 'button',
462+
ancestry: [{ role: 'toolbar', label: 42 }],
463+
verification: 'verified',
464+
}),
465+
),
466+
/"ancestry\[0\]\.label" must be a string/,
467+
);
468+
});
469+
470+
test('parser rejects a wrong-typed rect field, naming each in the message', () => {
471+
for (const field of ['x', 'y', 'width', 'height']) {
472+
assertInvalidArgs(
473+
() =>
474+
parseTargetAnnotationV1Payload(
475+
JSON.stringify({
476+
role: 'button',
477+
rect: { x: 1, y: 2, width: 3, height: 4, [field]: 'nope' },
478+
verification: 'verified',
479+
}),
480+
),
481+
new RegExp(`"rect\\.${field}" must be a finite number`),
482+
);
483+
}
484+
});
485+
486+
test('a whitespace-only label collapses to absent through the full parse, not just the normalizer', () => {
487+
const parsed = parseTargetAnnotationV1Payload(
488+
JSON.stringify({ role: 'button', label: ' ', verification: 'verified' }),
248489
);
490+
assert.equal(parsed.label, undefined);
249491
});
250492

251493
// ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)