Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Fixed

- Patching: correctly replace and delete tables split across dotted keys and headers, including nested inline-table paths. ([#335])
- Patching: keep nested sub-table replacements scoped to the selected array-of-tables entry and prevent table redefinition ([27a02a7]).

## [3.3.2] - 2026-10-31

### Fixed
Expand Down Expand Up @@ -530,5 +535,7 @@ This first forked version from [timhall/toml-patch](https://github.com/timhall/t
[#329]: https://github.com/DecimalTurn/toml-patch/pull/329
[#332]: https://github.com/DecimalTurn/toml-patch/pull/332
[#333]: https://github.com/DecimalTurn/toml-patch/pull/333
[#335]: https://github.com/DecimalTurn/toml-patch/issues/335
[0e66e68]: https://github.com/DecimalTurn/toml-patch/commit/0e66e68cbf42a07bc44445e46c3ea7bea97f95c1
[f97d571]: https://github.com/DecimalTurn/toml-patch/commit/f97d57194952b6603f0fcd686c32d3ae52a2c903
[27a02a7]: https://github.com/DecimalTurn/toml-patch/commit/27a02a746533d82026fe6f1fb6771f8e1ba5ac27
32 changes: 29 additions & 3 deletions docs/Fuzz-Testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,33 @@ general randomizer rarely creates the AOT ownership layouts it targets.
Its default is one mutation per seed. Every four consecutive seeds cover all
four mutation classes, while keeping failures easy to reproduce. Passing
`--mutations 3` applies additional deterministic mutations after the
seed-selected first operation.
seed-selected first operation. It does not generate dotted-key assignments
or inline tables, delete arbitrary table properties, or replace a table
property with a scalar. Those are the key shapes and operations in
[issue #335](https://github.com/DecimalTurn/toml-patch/issues/335).
- **Latest clean sweep:** On 2026-11-14, seeds 0 through 100,000 inclusive
(100,001 seeds, one mutation per seed, `--fast-fail`) completed with zero
failures.

### Variant 6: deletion and structural replacement fuzzing

- **Implementation:** `src/__tests__/fuzz-patch6.ts`
- **Runner:** `scripts/fuzz-run6.ts`, `pnpm run fuzz6`
- **Purpose:** Generates block tables with dotted-key assignments, tables with
nested AOT descendants, and inline tables with overlapping dotted paths. The
seed rotates among replacing a header-defined table with a scalar, deleting
a table that owns an AOT descendant, and replacing a nested inline-table
path.
- **Why it exists:** These source shapes and edits target the failures reported
in [issue #335](https://github.com/DecimalTurn/toml-patch/issues/335), which
the AOT-only generator in variant 5 cannot produce.
- **Reproducing the three targeted cases:** Seeds 0, 1 and 2 select each case
once. Use `--to 2` to run all three without stopping at the first failure.
- **Coverage boundary:** Variant 6 focuses on structural deletion and
replacement cases. A clean run is evidence only for the generated source
shapes and mutations, not a proof that every structural edit is correct.
- **Latest clean sweep:** On 2026-11-14, seeds 0 through 100,000 inclusive
(100,001 seeds, one mutation per seed) passed after rebasing onto `fix-335`.

### Patch-lite fuzzing

Expand Down Expand Up @@ -224,7 +250,8 @@ pnpm run fuzz5

The default is one mutation per seed, so each failure points to the seed's
selected operation. Passing `--mutations 3` to `scripts/fuzz-run5.ts` applies
two more deterministic AOT mutations after that first operation.
two more deterministic AOT mutations after that first operation. Pass
`--progress N` to report the scanned seed range every N seeds.

This runner behavior differs from the composable profiles above: `aot` and
`aot-format` always remove an AOT entry first, while `aot-general` uses the
Expand Down Expand Up @@ -515,4 +542,3 @@ The sweep-notes doc **must be committed** too — write it to
`docs: add sweep notes for <from>-<to>` message. A *clean* window (0 failures)
gets no notes file, but a window that needed fixes gets one, listing each seed,
its distilled minimal repro, and the root cause + fix commit.

1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@
"fuzz3": "npx -y tsx scripts/fuzz-run3.ts --seed 0 --to 9999 --mutations 3",
"fuzz4": "npx -y tsx scripts/fuzz-run4.ts --seed 0 --to 9999 --mutations 3",
"fuzz5": "npx -y tsx scripts/fuzz-run5.ts --seed 0 --to 9999 --mutations 1 --progress 100",
"fuzz6": "npx -y tsx scripts/fuzz-run6.ts --seed 0 --to 9999 --mutations 1 --progress 100",
"bench:bundle-size": "node benchmark/bundle-size.mjs",
"bench:parse": "node benchmark/parse-benchmark.mjs",
"bench:stringify": "node benchmark/stringify-benchmark.mjs",
Expand Down
10 changes: 10 additions & 0 deletions scripts/fuzz-run5.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
//
// Run a range:
// npx -y tsx scripts/fuzz-run5.ts --seed 0 --to 9999 --mutations 1
// Report progress every 100 seeds:
// npx -y tsx scripts/fuzz-run5.ts --seed 0 --to 9999 --mutations 1 --progress 100
// Stop at the first failure:
// npx -y tsx scripts/fuzz-run5.ts --seed 0 --to 9999 --mutations 1 --fast-fail
import { fuzzOne5 } from '../src/__tests__/fuzz-patch5';
Expand All @@ -16,13 +18,21 @@ const hasFlag = (name: string) => args.includes(`--${name}`);
const seed = param('seed', 0);
const to = param('to', seed);
const mutations = param('mutations', 1);
const progress = param('progress', 0);
const fastFail = hasFlag('fast-fail');
const failures: string[] = [];
let scanned = 0;

if (!Number.isInteger(progress) || progress < 0) {
throw new Error('--progress must be a non-negative integer.');
}

for (let current = seed; current <= to; current++) {
scanned++;
const result = fuzzOne5(current, mutations);
if (progress > 0 && scanned % progress === 0) {
console.log(`PROGRESS: scanned ${scanned} seeds (${seed}..${current})`);
}
if (result.status !== 'ok') {
const line = `SEED ${current} : ${result.status}${result.error ? ` | ${result.error}` : ''}`;
failures.push(line);
Expand Down
44 changes: 44 additions & 0 deletions scripts/fuzz-run6.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
// Fuzz-runner variant for dotted-key/header overlaps and structural replacements.
//
// Run an inclusive range:
// npx -y tsx scripts/fuzz-run6.ts --seed 0 --to 9999 --mutations 1
// Stop at the first failure:
// npx -y tsx scripts/fuzz-run6.ts --seed 0 --to 9999 --mutations 1 --fast-fail
import { fuzzOne6 } from '../src/__tests__/fuzz-patch6';

const args = process.argv.slice(2);
const param = (name: string, fallback: number) => {
const index = args.indexOf(`--${name}`);
return index >= 0 ? Number(args[index + 1]) : fallback;
};
const hasFlag = (name: string) => args.includes(`--${name}`);

const seed = param('seed', 0);
const to = param('to', seed);
const mutations = param('mutations', 1);
const progress = param('progress', 0);
const fastFail = hasFlag('fast-fail');
const failures: string[] = [];
let scanned = 0;

if (!Number.isInteger(progress) || progress < 0) {
throw new Error('--progress must be a non-negative integer.');
}

for (let current = seed; current <= to; current++) {
scanned++;
const result = fuzzOne6(current, mutations);
if (progress > 0 && scanned % progress === 0) {
console.log(`PROGRESS: scanned ${scanned} seeds (${seed}..${current})`);
}
if (result.status !== 'ok') {
const line = `SEED ${current} : ${result.status}${result.error ? ` | ${result.error.split('\n')[0]}` : ''}`;
failures.push(line);
console.log(line);
if (fastFail) break;
}
}

const end = seed + scanned - 1;
console.log(`FAILURES: ${failures.length} (scanned ${scanned} seeds: ${seed}..${end})`);
if (failures.length > 0) process.exit(1);
8 changes: 7 additions & 1 deletion scripts/report-dependents.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,13 @@
* The npm requests require network access. A names file is useful when the
* npm dependents page is unavailable or when the report should cover a fixed
* set of packages. Use `--refresh-names` to require a live npm refresh instead
* of falling back to cached names when npm is unavailable.
* of falling back to cached names when npm is unavailable. If the saved HTML
* page is stale, open the Dependents page in a browser, wait for it to finish
* loading, and save it again as <Webpage, HTML Only> to:
*
* docs/dependents/@decimalturn_toml-patch - npm.html
*
* Page URL: https://www.npmjs.com/package/@decimalturn/toml-patch?activeTab=dependents
*/
import { readFile, writeFile } from 'node:fs/promises';
import { execFile } from 'node:child_process';
Expand Down
176 changes: 176 additions & 0 deletions src/__tests__/fuzz-patch6.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
/**
* Structure-first patch fuzzer for deletions and table replacements.
*
* Each seed targets dotted-key/header overlap, deleting a table that owns an
* AOT descendant, or replacing a nested inline-table path.
*/
import { SeededRandom } from './randomizer';
import {
deepEqual,
runFuzz,
type FuzzContext,
type GeneratedSource,
type MutationPlan,
type MutationRun,
type PatchFuzzResult
} from './fuzz-patch';

type StructuralScenario =
| {
kind: 'replace-header-table';
path: string[];
replacement: string;
source: string;
}
| {
kind: 'delete-table-with-aot';
path: string[];
source: string;
}
| {
kind: 'replace-inline-table';
path: string[];
replacement: number[];
source: string;
};

function createScenario(seed: number, mutationIndex: number): StructuralScenario {
const rng = new SeededRandom(seed + mutationIndex * 100003 + 6000000);
const suffix = `${Math.abs(seed).toString(36)}_${mutationIndex.toString(36)}`;
const scenarioKind = ((seed + mutationIndex) % 3 + 3) % 3;

if (scenarioKind === 0) {
const root = `table_${suffix}`;
const child = `child_${suffix}`;
const sibling = `sibling_${suffix}`;
const target = `target_${suffix}`;
const replacement = `value_${suffix}_${rng.nextInt(1000)}`;
const source = [
`[${root}]`,
`${child}.${sibling} = ${JSON.stringify(`keep_${suffix}`)}`,
'',
`[${root}.${child}.${target}]`,
`value = ${rng.nextRange(-999, 999)}`
].join('\n') + '\n';

return {
kind: 'replace-header-table',
path: [root, child, target],
replacement,
source
};
}

if (scenarioKind === 1) {
const root = `table_${suffix}`;
const child = `child_${suffix}`;
const sibling = `sibling_${suffix}`;
const aot = `items_${suffix}`;
const source = [
`[${root}]`,
`${child}.${sibling} = ${JSON.stringify(`keep_${suffix}`)}`,
'',
`[[${root}.${child}.${aot}]]`,
`value = ${rng.nextRange(-999, 999)}`
].join('\n') + '\n';

return {
kind: 'delete-table-with-aot',
path: [root, child],
source
};
}

const root = `inline_${suffix}`;
const child = `child_${suffix}`;
const target = `target_${suffix}`;
const left = `left_${suffix}`;
const right = `right_${suffix}`;
const replacement = [rng.nextRange(-99, 99), rng.nextRange(-99, 99)];
const source = `${root} = { ${child}.${target}.${left} = ${rng.nextRange(-999, 999)}, ${child}.${target}.${right} = ${rng.nextRange(-999, 999)} }\n`;

return {
kind: 'replace-inline-table',
path: [root, child, target],
replacement,
source
};
}

function recordAtPath(value: unknown, path: string[]): Record<string, unknown> {
let current = value;
for (let index = 0; index < path.length; index++) {
if (!current || typeof current !== 'object' || Array.isArray(current) || current instanceof Date) {
throw new Error(`Expected a table at ${path.slice(0, index).join('.') || '<root>'}.`);
}
current = (current as Record<string, unknown>)[path[index]];
}

if (!current || typeof current !== 'object' || Array.isArray(current) || current instanceof Date) {
throw new Error(`Expected a table at ${path.join('.') || '<root>'}.`);
}
return current as Record<string, unknown>;
}

function generateStructuralSource(
{ seed, mutationCount }: Pick<FuzzContext, 'seed' | 'mutationCount'>
): GeneratedSource {
const scenarios = Array.from({ length: mutationCount }, (_, index) => createScenario(seed, index));
const inlineScenarios = scenarios.filter(scenario => scenario.kind === 'replace-inline-table');
const sectionScenarios = scenarios.filter(scenario => scenario.kind !== 'replace-inline-table');
return {
source: [...inlineScenarios, ...sectionScenarios].map(scenario => scenario.source).join('\n'),
description: 'dotted-key, AOT-deletion, and inline-table structural cases'
};
}

function mutateStructuralCases({
updated,
context
}: {
original: unknown;
updated: unknown;
context: FuzzContext;
}): MutationRun {
const descriptions: string[] = [];
const plans: MutationPlan[] = [];

for (let index = 0; index < context.mutationCount; index++) {
const scenario = createScenario(context.seed, index);
const path = scenario.path;
const parent = recordAtPath(updated, path.slice(0, -1));
const key = path[path.length - 1];

switch (scenario.kind) {
case 'replace-header-table':
parent[key] = scenario.replacement;
descriptions.push(`replace header-defined table with scalar at ${path.join('.')}`);
plans.push({ kind: scenario.kind, path, newValue: scenario.replacement });
break;
case 'delete-table-with-aot':
delete parent[key];
descriptions.push(`delete table with nested AOT descendant at ${path.join('.')}`);
plans.push({ kind: scenario.kind, path });
break;
case 'replace-inline-table':
parent[key] = scenario.replacement;
descriptions.push(`replace inline table subtree with array at ${path.join('.')}`);
plans.push({ kind: scenario.kind, path, newValue: scenario.replacement });
break;
}
}

return { updated, descriptions, plans };
}

export function fuzzOne6(seed: number, mutationCount: number): PatchFuzzResult {
return runFuzz(seed, {
mutationCount,
generateSource: generateStructuralSource,
generateFormat: () => undefined,
mutate: mutateStructuralCases,
compare: deepEqual,
variant: '6',
profile: 'structural-replacements'
});
}
30 changes: 30 additions & 0 deletions src/__tests__/fuzz6.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import { fuzzOne6 } from './fuzz-patch6';

test('fuzz6 rotates through the three targeted structural mutations', () => {
const results = [0, 1, 2].map(seed => fuzzOne6(seed, 1));

expect(results.map(result => result.mutationDescs?.[0]?.split(' at ')[0])).toEqual([
'replace header-defined table with scalar',
'delete table with nested AOT descendant',
'replace inline table subtree with array'
]);
});

test('fuzz6 seed 0 round-trips replacing a header-defined table with a scalar', () => {
expect(fuzzOne6(0, 1).status).toBe('ok');
});

test('fuzz6 seed 1 round-trips deleting a table that owns an AOT descendant', () => {
expect(fuzzOne6(1, 1).status).toBe('ok');
});

test('fuzz6 seed 2 round-trips replacing a nested inline-table path', () => {
expect(fuzzOne6(2, 1).status).toBe('ok');
});

test('fuzz6 seed 0 keeps root inline tables scoped correctly across three mutations', () => {
const result = fuzzOne6(0, 3);

expect(result.status, result.error).toBe('ok');
expect(result.mutationDescs).toHaveLength(3);
});
Loading
Loading