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
5 changes: 5 additions & 0 deletions .bumpy/extensible-mocking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
valimock: minor
---

Add `stringActions` and `stringFormats` options so libraries can register generators for their own string actions without replacing the built-in string generator. Pass a `mock` function as the third argument of `customMocks` entries so container overrides can recurse with the same instance. Flatten nested pipes when collecting constraints, so `v.pipe(v.pipe(...), ...)` no longer drops inner actions such as `integer`. Seed Faker once per top-level `mock()` call instead of before every nested value, so sibling fields with the same schema no longer receive identical values.
205 changes: 205 additions & 0 deletions OXC_VSCODE_ISSUE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
# Extension formats with oxfmt defaults instead of `vite.config.ts` when the raw oxfmt bin shadows the vite-plus wrapper at `node_modules/.bin/oxfmt`

> Target repo: [`oxc-project/oxc-vscode`](https://github.com/oxc-project/oxc-vscode)

### Confirm that this is a Bug for the editor extension, not the CLI

- [x] This bug does not happen in the Oxlint/Oxfmt CLI (`vp fmt` / `vp check --fix` are correct)
- [x] After restarting the editor, the bug still appears

### Versions used

```
VS Code extension (oxc.oxc-vscode): 1.57.0
oxfmt: 0.48.0 (transitive, via vite-plus)
vite-plus: 0.1.21
VS Code: freshly updated
OS: Windows 10 Pro 19045 (win32)
Node: v26.1.0
Package manager: yarn@4.14.1 (node-modules linker)
```

### What happened?

Format-on-save (Oxc extension) produces **different output than `vp fmt`** for the same
file and the same `vite.config.ts`, which has `fmt.trailingComma: "none"`.

Given this input (a long object literal that must wrap, so the last property lands on its
own line where a trailing comma would or wouldn't be added):

```ts
const longName = { alpha: 1, beta: 2, gamma: 3, delta: 4, epsilon: 5 };
```

`vp fmt` / `vp check --fix` — **no** trailing comma (config honored ✅):

```ts
const longName = {
alpha: 1,
beta: 2,
gamma: 3,
delta: 4,
epsilon: 5
};
```

Format-on-save via the extension — trailing comma **added** (oxfmt default, config ignored ❌):

```ts
const longName = {
alpha: 1,
beta: 2,
gamma: 3,
delta: 4,
epsilon: 5
};
```

The only difference is the comma after the last property (`epsilon: 5` vs `epsilon: 5,`).
`oxc.fmt.configPath` is `./vite.config.ts`. The extension silently falls back to oxfmt's
built-in defaults; only `trailingComma` visibly diverges because the other configured
values happen to match oxfmt's defaults.

### Root cause

oxfmt only reads `.fmt` from a `vite.config.ts` when the **`VP_VERSION`** env var is set
(it gates `vite.config.ts` recognition behind it — see
[`apps/oxfmt/src/core/utils.rs::vp_version()`](https://github.com/oxc-project/oxc/blob/e77ff81a6bf5aac5a3ed1627004c00e74f644adf/apps/oxfmt/src/core/utils.rs#L8-L10)).
`vp` injects `VP_VERSION`; the standalone binary does not. `vite-plus` ships a wrapper,
`vite-plus/bin/oxfmt`, whose sole job is to set `process.env.VP_VERSION` and delegate to
the real oxfmt:

```js
// vite-plus/bin/oxfmt (excerpt)
// This allows oxfmt to load vite.config.ts
process.env.VP_VERSION = pkg.version;
await import(pathToFileURL(oxfmtBin).href);
```

This wrapper is the binary the extension is meant to spawn. The extension prefers
`node_modules/.bin/<name>` precisely for this reason — and it documents that rationale at
[`findBinary.ts` L96–99](https://github.com/oxc-project/oxc-vscode/blob/91f7d365a12969ae2c40bedf32060747b6125a55/client/findBinary.ts#L96-L99):

> ```ts
> // try to find shared binary inside `node_modules/.bin` of each workspace folder
> // This is required, because the project can use `vite-plus`,
> // which has different environment variables for `oxlint` and `oxfmt`.
> // Example: It will skip the `vite.config.ts` search without `VP_VERSION` env variable.
> ```

The resolver builds the candidate path as
[`path.join(folder, ".bin", binaryName)`](https://github.com/oxc-project/oxc-vscode/blob/91f7d365a12969ae2c40bedf32060747b6125a55/client/findBinary.ts#L46)
inside
[`searchProjectNodeModulesBin`](https://github.com/oxc-project/oxc-vscode/blob/91f7d365a12969ae2c40bedf32060747b6125a55/client/findBinary.ts#L93-L111)
and trusts whatever that link resolves to.

**But two packages both claim the `oxfmt` bin name:**

- `vite-plus` → `bin/oxfmt` (the wrapper that sets `VP_VERSION`)
- `oxfmt` → `bin/oxfmt` (raw, no `VP_VERSION`)

`oxfmt` is **only a transitive dependency of `vite-plus`** (`yarn why oxfmt` →
`vite-plus@0.1.21 → oxfmt@0.48.0`), yet the raw `oxfmt` bin **won the
`node_modules/.bin/oxfmt` link**. So the extension — which prefers
`node_modules/.bin/oxfmt` — spawns the raw binary, no `VP_VERSION` flows, and oxfmt uses
defaults.

`node_modules/.bin/oxfmt.cmd` →

```
"%~dp0\node.exe" "%~dp0\..\oxfmt\bin\oxfmt" %* ← raw oxfmt, NOT vite-plus/bin/oxfmt
```

### Three-leg proof (same binary, same config, same input)

```sh
# 1. raw .bin path (what the extension resolves to) — no VP_VERSION → DEFAULT
$ node node_modules/oxfmt/bin/oxfmt --config ./vite.config.ts test.ts
→ epsilon: 5, ❌

# 2. same binary WITH VP_VERSION → config honored (proves the env var is the sole gate)
$ VP_VERSION=0.1.21 node node_modules/oxfmt/bin/oxfmt --config ./vite.config.ts test.ts
→ epsilon: 5 ✅

# 3. vp fmt (sets VP_VERSION + uses the wrapper) → config honored
$ vp fmt test.ts
→ epsilon: 5 ✅
```

### Why 1.53.0's fix doesn't cover this

[#215](https://github.com/oxc-project/oxc-vscode/issues/215) (closed) fixed a related case
by making the extension prefer `node_modules/.bin/oxfmt` (shipped in extension 1.53.0).
That assumes `.bin/oxfmt` **is** the vite-plus wrapper. When the raw `oxfmt` package wins
the bin-name collision (as here — and it can, since vite-plus pulls oxfmt in transitively
and the linker resolves the `.bin` race non-deterministically), that assumption breaks and
the user is silently back on defaults.

### Suggested fix

In [`searchProjectNodeModulesBin`](https://github.com/oxc-project/oxc-vscode/blob/91f7d365a12969ae2c40bedf32060747b6125a55/client/findBinary.ts#L93-L111),
when the workspace has `vite-plus` installed, prefer **`node_modules/vite-plus/bin/oxfmt`**
(and `…/bin/oxlint`) directly rather than the `node_modules/.bin/<name>` link built at
[L46](https://github.com/oxc-project/oxc-vscode/blob/91f7d365a12969ae2c40bedf32060747b6125a55/client/findBinary.ts#L46).
This makes resolution deterministic regardless of how the bin-link race resolved, and
matches the rationale the function already documents. Fall back to the current `.bin`
behavior when `vite-plus` isn't present.

(Alternatively/additionally, the extension could verify a resolved `.bin/<name>` actually
points into `vite-plus/` before trusting it for the VP_VERSION path — but resolving the
wrapper directly is simpler and avoids the race entirely.)

### Minimal reproduction (from scratch — no special project needed)

`@saeris/configs` is **not** involved; an inline `fmt` reproduces it. The only non-obvious
requirement is that the formatted construct must **wrap** (exceed `printWidth`, default 80),
since `trailingComma` only applies to multi-line output — hence the long variable name below.

1. New folder, install vite-plus (any package manager; the collision is in the dep tree):

```sh
npm init -y
npm install vite-plus
```

This installs both `vite-plus/bin/oxfmt` (the `VP_VERSION` wrapper) and, transitively,
`oxfmt/bin/oxfmt` (raw) — both claiming the `oxfmt` bin name.

2. `vite.config.ts` with a non-default fmt option:

```ts
import { defineConfig } from "vite-plus";

export default defineConfig({
fmt: { trailingComma: "none" }
});
```

3. `test.ts` (long enough that the object must wrap):

```ts
const aReallyLongVariableNameSoTheObjectMustWrapAcrossMultipleLines = {
alpha: 1,
beta: 2,
gamma: 3,
delta: 4,
epsilon: 5
};
```

4. VS Code settings: `"editor.defaultFormatter": "oxc.oxc-vscode"`,
`"editor.formatOnSave": true`, `"oxc.fmt.configPath": "./vite.config.ts"`.

5. Open `test.ts`, save → trailing comma is **added** (`epsilon: 5,`), but `vp fmt test.ts`
produces **no** trailing comma (`epsilon: 5`).

Check which binary `.bin/oxfmt` resolves to — if it points into `oxfmt/` rather than
`vite-plus/`, the extension is spawning the raw binary and the bug is present. The
three-leg proof above can be run against this same setup.

> **Note on the bin race:** which of the two competing `oxfmt` bins ends up at
> `node_modules/.bin/oxfmt` is decided by the package manager / linker and isn't
> guaranteed to be the raw one on every install — but when it is the raw one (as observed
> here), the extension has no way to tell and silently uses defaults. The fix removes the
> dependence on that race entirely by resolving the `vite-plus` wrapper directly. You can
> force the failing state for testing by pointing `.bin/oxfmt` at `../oxfmt/bin/oxfmt`.
91 changes: 72 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,23 @@ yarn add -D valimock @faker-js/faker
Import and optionally configure a new instance of the `Valimock` class, then pass along your `valibot` schema to `mock()`, that's it!

```ts
import { parse, array, union, string, pipe, url, number, maxValue } from "valibot";
import {
parse,
array,
union,
string,
pipe,
url,
number,
maxValue
} from "valibot";
import { Valimock } from "valimock";

describe(`example test`, () => {
it(`should generate valid mock data`, () => {
const schema = array(union([pipe(string(), url()), pipe(number(), maxValue(20))]));
const schema = array(
union([pipe(string(), url()), pipe(number(), maxValue(20))])
);
const result = new Valimock().mock(schema);
expect(parse(schema, result)).toStrictEqual(result);
});
Expand All @@ -54,30 +65,72 @@ describe(`example test`, () => {

`new Valimock(options)` accepts a partial options object:

| option | type | default | purpose |
| -------------------- | ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `faker` | `Faker` | default Faker instance | Faker instance used for all generation; supply your own to control locale or seeding centrally |
| `seed` | `number \| number[]` | `undefined` | Re-seeds Faker on every `mock()` call for deterministic output |
| `stringMap` | `Record<string, () => string>` | `undefined` | Per-key string overrides (when generating strings inside an object). Wins over the built-in format/key-name routing. |
| `customMocks` | `Record<string, (schema) => unknown>` | `{}` | Generators for Valibot schema `type`s Valimock doesn't yet support. Keyed by `schema.type`. |
| `recordKeysLength` | `number` | `1` | How many entries to generate for a `record()` schema |
| `mapEntriesLength` | `number` | `1` | How many entries to generate for a `map()` schema |
| `throwOnUnknownType` | `boolean` | `false` | When true, throw a `MockError` for unrecognized schema types instead of warning |
| `onWarn` | `(message: string) => void` | `console.warn` | Diagnostic sink. Receives unhandled-action notices, retry-budget exhaustion, and generation errors. Set to `() => {}` to silence. |
| `mockeryMapper` | `MockeryMapper` | built-in defaults | **Deprecated.** Prefer `stringMap` or contributing an action handler. Still consulted for backwards compatibility; emits a one-time warning when invoked. |
| option | type | default | purpose |
| -------------------- | ---------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `faker` | `Faker` | default Faker instance | Faker instance used for all generation; supply your own to control locale or seeding centrally |
| `seed` | `number \| number[]` | `undefined` | Re-seeds Faker at the start of every top-level `mock()` call for deterministic output |
| `stringMap` | `Record<string, () => string>` | `undefined` | Per-key string overrides (when generating strings inside an object). Wins over the built-in format/key-name routing. |
| `stringActions` | `Record<string, StringActionHandler>` | `{}` | Handlers for string pipe actions Valimock doesn't know, keyed by action `type`. See [Extending string generation](#extending-string-generation). |
| `stringFormats` | `Record<string, StringFormatGenerator>` | `{}` | Generators for the format names your `stringActions` handlers record in `ctx.format`. |
| `customMocks` | `Record<string, (schema, options, mock) => unknown>` | `{}` | Generators for Valibot schema `type`s Valimock doesn't yet support. Keyed by `schema.type`; `mock` recurses into nested schemas with the same instance. |
| `recordKeysLength` | `number` | `1` | How many entries to generate for a `record()` schema |
| `mapEntriesLength` | `number` | `1` | How many entries to generate for a `map()` schema |
| `throwOnUnknownType` | `boolean` | `false` | When true, throw a `MockError` for unrecognized schema types instead of warning |
| `onWarn` | `(message: string) => void` | `console.warn` | Diagnostic sink. Receives unhandled-action notices, retry-budget exhaustion, and generation errors. Set to `() => {}` to silence. |
| `mockeryMapper` | `MockeryMapper` | built-in defaults | **Deprecated.** Prefer `stringMap` or contributing an action handler. Still consulted for backwards compatibility; emits a one-time warning when invoked. |

### Extending string generation

Libraries that ship their own string actions (`v.pipe(v.string(), did())`)
can teach Valimock to generate matching values without replacing the whole
string generator. A `stringActions` handler runs when its action `type` is
found in a pipe and records what it learned on the `StringContext`, usually
by naming a format; a `stringFormats` generator with that name then produces
the value. Everything else (length bounds, `stringMap`, key-name heuristics)
keeps working around them.

```ts
import { Valimock } from "valimock";

const mock = new Valimock({
stringActions: {
// `did()` is a validation action with `type: "did"`.
did: (ctx) => {
ctx.format = `did`;
},
// Handlers can read the action's requirement and stash it for the
// generator in `ctx.custom`.
accept: (ctx, action) => {
ctx.format = `mime`;
ctx.custom.accept = (action as { requirement: string[] }).requirement;
}
},
stringFormats: {
did: (ctx) => `did:plc:${ctx.faker.string.alphanumeric(24).toLowerCase()}`,
mime: (ctx) => ctx.faker.helpers.arrayElement(ctx.custom.accept as string[])
}
});
```

Both tables are merged over the built-in registries, so an entry can also
override how Valimock handles one of its own actions.

## API Coverage

Valimock's string mocking is built around a small pipeline (`src/schemas/string/`)
with a per-action registry. Adding support for a new Valibot action is a
one-line addition to the registry. See [Contributing](#-contributing) below.
one-line addition to the registry, or a `stringActions` entry from userland.
See [Contributing](#-contributing) below.

Any schema type Valimock doesn't yet support can be handled by supplying a
`customMocks` entry keyed by the schema's `type` field. When Valimock has
no built-in mocker and no matching `customMocks` entry (notably for
`v.custom(...)`), it emits an `onWarn` notice and returns `undefined`
rather than silently producing an invalid value. Set
`throwOnUnknownType: true` to turn that into a thrown `MockError`.
`customMocks` entry keyed by the schema's `type` field. The entry receives
the schema, the instance options, and a `mock` function that recurses into
nested schemas with the same instance, so container types can be mocked
without constructing a second `Valimock`. When Valimock has no built-in
mocker and no matching `customMocks` entry (notably for `v.custom(...)`), it
emits an `onWarn` notice and returns `undefined` rather than silently
producing an invalid value. Set `throwOnUnknownType: true` to turn that into
a thrown `MockError`.

### Schemas

Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
},
"devDependencies": {
"@faker-js/faker": "^10.4.0",
"@saeris/configs": "1.6.0",
"@types/node": "25.8.0",
"@varlock/bumpy": "^1.7.0",
"@vitest/coverage-v8": "^4.1.6",
Expand Down
17 changes: 14 additions & 3 deletions scripts/profile.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,22 @@ console.log(`>> Bench filter: ${process.argv.slice(2).join(` `) || `(all)`}`);
// not the vp wrapper.
const vitestBin = join(repoRoot, `node_modules/vitest/dist/cli.js`);
if (!existsSync(vitestBin)) {
console.error(`error: vitest CLI not found at ${vitestBin}. Run \`vp install\` first.`);
console.error(
`error: vitest CLI not found at ${vitestBin}. Run \`vp install\` first.`
);
process.exit(1);
}

const result = spawnSync(
process.execPath,
[`--cpu-prof`, `--cpu-prof-dir=${profilesDir}`, vitestBin, `bench`, `--run`, ...process.argv.slice(2)],
[
`--cpu-prof`,
`--cpu-prof-dir=${profilesDir}`,
vitestBin,
`bench`,
`--run`,
...process.argv.slice(2)
],
{ stdio: `inherit`, cwd: repoRoot }
);

Expand All @@ -55,7 +64,9 @@ const cpuProfiles = readdirSync(profilesDir)
.sort((a, b) => b.mtime - a.mtime);

if (cpuProfiles.length === 0) {
console.warn(`>> No .cpuprofile files written — check that vitest actually ran.`);
console.warn(
`>> No .cpuprofile files written — check that vitest actually ran.`
);
process.exit(1);
}

Expand Down
Loading
Loading