hazo_testing 0.4.1 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGE_LOG.md +119 -0
- package/dist/audio/audio_stub.d.ts +73 -0
- package/dist/audio/audio_stub.js +114 -0
- package/dist/components/test_providers.d.ts +2 -2
- package/dist/components/test_providers.js +6 -8
- package/dist/db/augmented_adapter.d.ts +25 -0
- package/dist/i18n/scan_translation_usage.d.ts +31 -0
- package/dist/i18n/scan_translation_usage.js +132 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/internal/resolve_peer.d.ts +4 -0
- package/dist/internal/resolve_peer.js +40 -0
- package/dist/render_with_intl.d.ts +3 -2
- package/dist/render_with_intl.js +14 -5
- package/package.json +14 -6
- package/vitest-preset.mjs +13 -7
package/CHANGE_LOG.md
CHANGED
|
@@ -1,5 +1,124 @@
|
|
|
1
1
|
# hazo_testing changelog
|
|
2
2
|
|
|
3
|
+
## 0.5.2 — 2026-10-18
|
|
4
|
+
|
|
5
|
+
### Fixed — dual-React-copy crash in `renderWithIntl`/`TestProviders` when consumed via `file:` link
|
|
6
|
+
|
|
7
|
+
A consumer reported `renderWithIntl` (`hazo_testing/render`) crashing with
|
|
8
|
+
"Objects are not valid as a React child" when hazo_testing is wired in via a
|
|
9
|
+
`file:` dependency that points at a real directory living outside the
|
|
10
|
+
consumer's own `node_modules` tree — exactly how gotimer consumes this
|
|
11
|
+
package from the `00.lib` monorepo checkout.
|
|
12
|
+
|
|
13
|
+
`react`, `react-dom`, and `@testing-library/react` were already correctly
|
|
14
|
+
declared as `peerDependencies` (not `dependencies`), and the build (`tsc`,
|
|
15
|
+
no bundler) does not inline them — both suspected causes from the bug report
|
|
16
|
+
checked out clean. The actual root cause: `render_with_intl.tsx` and
|
|
17
|
+
`components/test_providers.tsx` imported `react` with a bare specifier from
|
|
18
|
+
their own on-disk location. Resolved via Node's normal upward directory
|
|
19
|
+
walk, a bare `"react"` import from hazo_testing's *real* path (not the
|
|
20
|
+
consumer's symlinked path) can land on an unrelated copy hoisted in an
|
|
21
|
+
ancestor `node_modules` — in this case the `00.lib` npm-workspace root,
|
|
22
|
+
which hoists a different React (18.3.1) than gotimer's own installed copy
|
|
23
|
+
(19.1.0). Confirmed by direct `createRequire(...).resolve('react')`
|
|
24
|
+
experiments from both anchor points. Two React module instances in one
|
|
25
|
+
render tree breaks reconciliation regardless of how `peerDependencies` is
|
|
26
|
+
declared — that field is an install-time contract, not a runtime resolution
|
|
27
|
+
mechanism, and it can't steer resolution across a `file:` link's realpath
|
|
28
|
+
boundary.
|
|
29
|
+
|
|
30
|
+
Fix: added `src/internal/resolve_peer.ts` (`resolve_peer_path`/`import_peer`),
|
|
31
|
+
which resolves a bare peer specifier anchored to `process.cwd()` — the
|
|
32
|
+
consumer's own project root when its test runner invokes Jest/Vitest —
|
|
33
|
+
instead of to the importing file's location. `render_with_intl.tsx` and
|
|
34
|
+
`test_providers.tsx` now resolve `react` (and, in `render_with_intl.tsx`,
|
|
35
|
+
`next-intl` and `@testing-library/react`) through this helper. No public API
|
|
36
|
+
change — `renderWithIntl`, `TestProviders`, and `useTestContext` keep their
|
|
37
|
+
existing signatures.
|
|
38
|
+
|
|
39
|
+
Added `src/internal/__tests__/resolve_peer_consumer_{a,b}.test.ts` and
|
|
40
|
+
`resolve_peer_no_peer.test.ts`: each chdir's into a different fixture
|
|
41
|
+
"consumer" directory and asserts `resolve_peer_path` picks up that
|
|
42
|
+
directory's own copy of a fixture peer package, and throws rather than
|
|
43
|
+
silently falling back to an ancestor's `node_modules` when the consumer
|
|
44
|
+
directory has none. A true cross-package repro (two real installed React
|
|
45
|
+
copies) would need a second real consumer project and isn't feasible inside
|
|
46
|
+
this package's own suite, but these tests exercise the exact resolution
|
|
47
|
+
mechanism the fix relies on.
|
|
48
|
+
|
|
49
|
+
## 0.5.1 — 2026-10-18
|
|
50
|
+
|
|
51
|
+
### Fixed — `AugmentedAdapter` type missing `execScript`/`transaction`
|
|
52
|
+
|
|
53
|
+
`createTestDatabase()`'s returned `adapter` is always backed by a real
|
|
54
|
+
hazo_connect `SqliteAdapter` instance (the only supported mode — `"docker"`
|
|
55
|
+
throws `DockerNotSupported`), and that concrete class has public
|
|
56
|
+
`execScript(sql)` and `transaction(fn, opts)` methods that worked fine at
|
|
57
|
+
runtime. But the exported `AugmentedAdapter` TypeScript type only extended
|
|
58
|
+
`HazoConnectAdapter`, whose own interface doesn't declare either method — so
|
|
59
|
+
any consumer typing a test against `Awaited<ReturnType<typeof
|
|
60
|
+
createTestDatabase>>["adapter"]` and calling `adapter.execScript(ddl)` or
|
|
61
|
+
`adapter.transaction(fn)` got a compile error even though the call worked.
|
|
62
|
+
Found while migrating GoTimer's 12 raw-SQL test files off a local
|
|
63
|
+
better-sqlite3 helper onto `createTestDatabase` (ticket 03) — several needed
|
|
64
|
+
`execScript` for inline DDL strings (not file-backed `setupSqlFiles`) and
|
|
65
|
+
`transaction` to exercise migration-runner-style code under test.
|
|
66
|
+
|
|
67
|
+
`AugmentedAdapter` now declares both methods explicitly, matching
|
|
68
|
+
`SqliteAdapter`'s real signatures. No runtime change — `augmentAdapter()`
|
|
69
|
+
already passed the real adapter object through untouched.
|
|
70
|
+
|
|
71
|
+
## 0.5.0 — 2026-10-18
|
|
72
|
+
|
|
73
|
+
### Added — `createAudioStub` (`hazo_testing/audio`)
|
|
74
|
+
|
|
75
|
+
A reusable Web Audio / `HTMLAudioElement` test double, generalised from the
|
|
76
|
+
pattern proven in gotimer's `use-audio.test.ts` (jsdom has no WebAudio and no
|
|
77
|
+
file-based `Audio` playback). Framework-agnostic — no `vi`/`jest` import, so
|
|
78
|
+
it works unchanged under Vitest or Jest.
|
|
79
|
+
|
|
80
|
+
`createAudioStub()` returns `{ AudioContext, Audio, oscillators, gains,
|
|
81
|
+
audioInstances, reset() }`:
|
|
82
|
+
|
|
83
|
+
- `AudioContext` — assign to `window.AudioContext`. Constructible with `new`;
|
|
84
|
+
`createOscillator()`/`createGain()` push every node onto `oscillators`/`gains`
|
|
85
|
+
for direct inspection (type, `frequency.value`, `stop_at`, gain scheduling
|
|
86
|
+
calls in order).
|
|
87
|
+
- `Audio` — assign to `window.Audio`/`global.Audio` to stub file-based
|
|
88
|
+
playback (`new Audio(src)`); records `src`, `play_count`, `pause_count`,
|
|
89
|
+
`paused` per instance in `audioInstances`.
|
|
90
|
+
- `reset()` clears all three recording arrays without replacing the
|
|
91
|
+
constructors (so a shared stub can be reused across tests via `beforeEach`).
|
|
92
|
+
|
|
93
|
+
### Added — `scanTranslationUsage` (`hazo_testing/i18n`)
|
|
94
|
+
|
|
95
|
+
A static-analysis check that greps `.ts`/`.tsx` source for literal
|
|
96
|
+
`t("key")`/`t('key')` call sites and diffs them against a flattened JSON
|
|
97
|
+
message catalog (nested objects flattened to dot-notation leaf keys).
|
|
98
|
+
|
|
99
|
+
`scanTranslationUsage(srcDir, catalogPath, options?)` returns
|
|
100
|
+
`{ missing, unused }`:
|
|
101
|
+
|
|
102
|
+
- `missing` — keys referenced by a literal `t()` call but absent from the
|
|
103
|
+
catalog.
|
|
104
|
+
- `unused` — catalog keys never referenced by a literal `t()` call.
|
|
105
|
+
- Only literal string-argument calls are matched — `t(someVar)` or
|
|
106
|
+
`t(\`a.${i}.b\`)` has no string literal to capture and is silently skipped,
|
|
107
|
+
never misreported.
|
|
108
|
+
- `options.allowlist` marks catalog keys reached only via a computed/dynamic
|
|
109
|
+
`t()` call as "used" so they aren't false-flagged as `unused`. Entries
|
|
110
|
+
support a trailing `*` dot-prefix wildcard (e.g. `"faq.*"`).
|
|
111
|
+
- `options.extensions` / `options.ignoreDirs` narrow the file walk.
|
|
112
|
+
|
|
113
|
+
### Fixed — `vitest-preset.mjs` `deps.inline` mis-nesting
|
|
114
|
+
|
|
115
|
+
`server.deps.inline` was nested under a top-level `server` key. That collides
|
|
116
|
+
with Vite's own `server` (`ServerOptions`, e.g. dev-server `server.fs.allow`)
|
|
117
|
+
and broke `tsc --noEmit` for any consumer that spread this factory's return
|
|
118
|
+
value into `defineConfig` while also setting real `server` options. Moved to
|
|
119
|
+
the correct location, `test.server.deps.inline`. Found during gotimer's
|
|
120
|
+
hazo_testing adoption (ticket 01).
|
|
121
|
+
|
|
3
122
|
## 0.4.1 — 2026-09-19
|
|
4
123
|
|
|
5
124
|
### Added — i18n future-proofing plumbing (no behavior change)
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/** A recorded call to one of a GainNode's `AudioParam` scheduling methods. */
|
|
2
|
+
export interface AudioStubGainScheduleEntry {
|
|
3
|
+
method: "setValueAtTime" | "linearRampToValueAtTime" | "exponentialRampToValueAtTime";
|
|
4
|
+
value: number;
|
|
5
|
+
time: number;
|
|
6
|
+
}
|
|
7
|
+
/** Mock `OscillatorNode` — records type/frequency and the `stop()` time. */
|
|
8
|
+
export interface AudioStubOscillator {
|
|
9
|
+
type: string;
|
|
10
|
+
frequency: {
|
|
11
|
+
value: number;
|
|
12
|
+
};
|
|
13
|
+
detune: {
|
|
14
|
+
value: number;
|
|
15
|
+
};
|
|
16
|
+
/** `null` until `stop()` is called. */
|
|
17
|
+
stop_at: number | null;
|
|
18
|
+
connect(...args: unknown[]): void;
|
|
19
|
+
start(...args: unknown[]): void;
|
|
20
|
+
stop(at?: number): void;
|
|
21
|
+
}
|
|
22
|
+
/** Mock `GainNode` — records every scheduling call against `.gain`. */
|
|
23
|
+
export interface AudioStubGainNode {
|
|
24
|
+
gain: {
|
|
25
|
+
value: number;
|
|
26
|
+
setValueAtTime(value: number, time: number): void;
|
|
27
|
+
linearRampToValueAtTime(value: number, time: number): void;
|
|
28
|
+
exponentialRampToValueAtTime(value: number, time: number): void;
|
|
29
|
+
};
|
|
30
|
+
/** Every scheduling call made against `.gain`, in call order. */
|
|
31
|
+
gain_schedule: AudioStubGainScheduleEntry[];
|
|
32
|
+
connect(...args: unknown[]): void;
|
|
33
|
+
}
|
|
34
|
+
/** Mock `HTMLAudioElement` instance produced by the stubbed `Audio` constructor. */
|
|
35
|
+
export interface AudioStubFileInstance {
|
|
36
|
+
src: string;
|
|
37
|
+
loop: boolean;
|
|
38
|
+
volume: number;
|
|
39
|
+
currentTime: number;
|
|
40
|
+
paused: boolean;
|
|
41
|
+
play_count: number;
|
|
42
|
+
pause_count: number;
|
|
43
|
+
play(): Promise<void>;
|
|
44
|
+
pause(): void;
|
|
45
|
+
addEventListener(...args: unknown[]): void;
|
|
46
|
+
removeEventListener(...args: unknown[]): void;
|
|
47
|
+
}
|
|
48
|
+
export interface AudioStubHandle {
|
|
49
|
+
/**
|
|
50
|
+
* Assign to `window.AudioContext` (must be constructed with `new` by
|
|
51
|
+
* consumer code — this IS constructible, unlike an arrow-fn mock).
|
|
52
|
+
*/
|
|
53
|
+
AudioContext: new (...args: unknown[]) => {
|
|
54
|
+
state: string;
|
|
55
|
+
resume(): Promise<void>;
|
|
56
|
+
createOscillator(): AudioStubOscillator;
|
|
57
|
+
createGain(): AudioStubGainNode;
|
|
58
|
+
readonly currentTime: number;
|
|
59
|
+
destination: Record<string, never>;
|
|
60
|
+
close(): Promise<void>;
|
|
61
|
+
};
|
|
62
|
+
/** Assign to `window.Audio` / `global.Audio` to stub file-based playback. */
|
|
63
|
+
Audio: new (src?: string) => AudioStubFileInstance;
|
|
64
|
+
/** Every `createOscillator()` result, across every `AudioContext` instance, in creation order. */
|
|
65
|
+
oscillators: AudioStubOscillator[];
|
|
66
|
+
/** Every `createGain()` result, across every `AudioContext` instance, in creation order. */
|
|
67
|
+
gains: AudioStubGainNode[];
|
|
68
|
+
/** Every `new Audio(...)` instance, in creation order. */
|
|
69
|
+
audioInstances: AudioStubFileInstance[];
|
|
70
|
+
/** Clears all three recording arrays without replacing the constructors. */
|
|
71
|
+
reset(): void;
|
|
72
|
+
}
|
|
73
|
+
export declare function createAudioStub(): AudioStubHandle;
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
// src/audio/audio_stub.ts
|
|
2
|
+
// Purpose: a reusable Web Audio / HTMLAudioElement test double, lifted from
|
|
3
|
+
// the pattern proven in gotimer's `src/hooks/timer/use-audio.test.ts` (jsdom
|
|
4
|
+
// has no WebAudio, and no file-based `Audio` playback). Framework-agnostic —
|
|
5
|
+
// no `vi`/`jest` import — so it works unmodified under Vitest or Jest. Every
|
|
6
|
+
// node/instance the stub creates is pushed onto a plain array for direct
|
|
7
|
+
// inspection (`toHaveLength`, index into `[0]`, etc.) rather than relying on
|
|
8
|
+
// a spy API.
|
|
9
|
+
//
|
|
10
|
+
// Usage (consumer test, oscillator-based synth beep):
|
|
11
|
+
// const stub = createAudioStub();
|
|
12
|
+
// window.AudioContext = stub.AudioContext;
|
|
13
|
+
// // ... exercise code that does `new AudioContext()` ...
|
|
14
|
+
// expect(stub.oscillators).toHaveLength(1);
|
|
15
|
+
// expect(stub.oscillators[0].frequency.value).toBe(660);
|
|
16
|
+
//
|
|
17
|
+
// Usage (file-based playback, e.g. `new Audio("/sounds/bell.mp3")`):
|
|
18
|
+
// window.Audio = stub.Audio as unknown as typeof Audio;
|
|
19
|
+
// // ... exercise code that does `new Audio(src)` and calls `.play()` ...
|
|
20
|
+
// expect(stub.audioInstances[0].src).toBe("/sounds/bell.mp3");
|
|
21
|
+
// expect(stub.audioInstances[0].play_count).toBe(1);
|
|
22
|
+
export function createAudioStub() {
|
|
23
|
+
const oscillators = [];
|
|
24
|
+
const gains = [];
|
|
25
|
+
const audioInstances = [];
|
|
26
|
+
function makeOscillator() {
|
|
27
|
+
const osc = {
|
|
28
|
+
type: "sine",
|
|
29
|
+
frequency: { value: 0 },
|
|
30
|
+
detune: { value: 0 },
|
|
31
|
+
stop_at: null,
|
|
32
|
+
connect() { },
|
|
33
|
+
start() { },
|
|
34
|
+
stop(at) {
|
|
35
|
+
osc.stop_at = at ?? 0;
|
|
36
|
+
},
|
|
37
|
+
};
|
|
38
|
+
oscillators.push(osc);
|
|
39
|
+
return osc;
|
|
40
|
+
}
|
|
41
|
+
function makeGain() {
|
|
42
|
+
const gain_schedule = [];
|
|
43
|
+
const node = {
|
|
44
|
+
gain: {
|
|
45
|
+
value: 1,
|
|
46
|
+
setValueAtTime(value, time) {
|
|
47
|
+
node.gain.value = value;
|
|
48
|
+
gain_schedule.push({ method: "setValueAtTime", value, time });
|
|
49
|
+
},
|
|
50
|
+
linearRampToValueAtTime(value, time) {
|
|
51
|
+
node.gain.value = value;
|
|
52
|
+
gain_schedule.push({ method: "linearRampToValueAtTime", value, time });
|
|
53
|
+
},
|
|
54
|
+
exponentialRampToValueAtTime(value, time) {
|
|
55
|
+
node.gain.value = value;
|
|
56
|
+
gain_schedule.push({ method: "exponentialRampToValueAtTime", value, time });
|
|
57
|
+
},
|
|
58
|
+
},
|
|
59
|
+
gain_schedule,
|
|
60
|
+
connect() { },
|
|
61
|
+
};
|
|
62
|
+
gains.push(node);
|
|
63
|
+
return node;
|
|
64
|
+
}
|
|
65
|
+
// Must be a real `function` (not an arrow fn) — consumer code constructs
|
|
66
|
+
// this with `new AudioContext()`, and arrow functions aren't constructible.
|
|
67
|
+
function AudioContextStub() {
|
|
68
|
+
return {
|
|
69
|
+
state: "running",
|
|
70
|
+
async resume() { },
|
|
71
|
+
createOscillator: makeOscillator,
|
|
72
|
+
createGain: makeGain,
|
|
73
|
+
get currentTime() {
|
|
74
|
+
return 0;
|
|
75
|
+
},
|
|
76
|
+
destination: {},
|
|
77
|
+
async close() { },
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
// Same constructibility requirement as AudioContextStub above.
|
|
81
|
+
function AudioFileStub(src) {
|
|
82
|
+
this.src = src ?? "";
|
|
83
|
+
this.loop = false;
|
|
84
|
+
this.volume = 1;
|
|
85
|
+
this.currentTime = 0;
|
|
86
|
+
this.paused = true;
|
|
87
|
+
this.play_count = 0;
|
|
88
|
+
this.pause_count = 0;
|
|
89
|
+
this.play = async () => {
|
|
90
|
+
this.paused = false;
|
|
91
|
+
this.play_count += 1;
|
|
92
|
+
};
|
|
93
|
+
this.pause = () => {
|
|
94
|
+
this.paused = true;
|
|
95
|
+
this.pause_count += 1;
|
|
96
|
+
};
|
|
97
|
+
this.addEventListener = () => { };
|
|
98
|
+
this.removeEventListener = () => { };
|
|
99
|
+
audioInstances.push(this);
|
|
100
|
+
}
|
|
101
|
+
function reset() {
|
|
102
|
+
oscillators.length = 0;
|
|
103
|
+
gains.length = 0;
|
|
104
|
+
audioInstances.length = 0;
|
|
105
|
+
}
|
|
106
|
+
return {
|
|
107
|
+
AudioContext: AudioContextStub,
|
|
108
|
+
Audio: AudioFileStub,
|
|
109
|
+
oscillators,
|
|
110
|
+
gains,
|
|
111
|
+
audioInstances,
|
|
112
|
+
reset,
|
|
113
|
+
};
|
|
114
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import React from "react";
|
|
1
|
+
import type React from "react";
|
|
2
2
|
export interface TestUserCtx {
|
|
3
3
|
id: string;
|
|
4
4
|
email: string;
|
|
@@ -16,5 +16,5 @@ export declare function TestProviders(props: {
|
|
|
16
16
|
user?: TestUserCtx;
|
|
17
17
|
scope?: TestScopeCtx;
|
|
18
18
|
children: React.ReactNode;
|
|
19
|
-
}):
|
|
19
|
+
}): React.FunctionComponentElement<React.ProviderProps<TestCtxValue>>;
|
|
20
20
|
export {};
|
|
@@ -1,10 +1,8 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
const TestCtx = createContext({});
|
|
7
|
-
export const useTestContext = () => useContext(TestCtx);
|
|
1
|
+
import { import_peer } from "../internal/resolve_peer.js";
|
|
2
|
+
const react_mod = await import_peer("react");
|
|
3
|
+
const react_ns = react_mod.default ?? react_mod;
|
|
4
|
+
const TestCtx = react_ns.createContext({});
|
|
5
|
+
export const useTestContext = () => react_ns.useContext(TestCtx);
|
|
8
6
|
export function TestProviders(props) {
|
|
9
|
-
return
|
|
7
|
+
return react_ns.createElement(TestCtx.Provider, { value: { user: props.user, scope: props.scope } }, props.children);
|
|
10
8
|
}
|
|
@@ -4,5 +4,30 @@ export interface AugmentedAdapter extends HazoConnectAdapter {
|
|
|
4
4
|
id: string;
|
|
5
5
|
}>;
|
|
6
6
|
findOne<T = Record<string, unknown>>(table: string, where: Record<string, unknown>): Promise<T | null>;
|
|
7
|
+
/**
|
|
8
|
+
* Execute one or more semicolon-separated SQL statements (DDL / migration
|
|
9
|
+
* scripts; no parameterisation). `createTestDatabase` always backs
|
|
10
|
+
* `adapter` with a real hazo_connect `SqliteAdapter` instance (the only
|
|
11
|
+
* supported mode — `"docker"` throws `DockerNotSupported`), and that
|
|
12
|
+
* concrete class declares a public `execScript` — but `HazoConnectAdapter`
|
|
13
|
+
* (the interface this type otherwise mirrors) does not, so it was
|
|
14
|
+
* invisible to consumers typing against `AugmentedAdapter` even though it
|
|
15
|
+
* works at runtime. Declared here so test code can call
|
|
16
|
+
* `adapter.execScript(ddl)` directly instead of only through
|
|
17
|
+
* `setupSqlFiles`.
|
|
18
|
+
*/
|
|
19
|
+
execScript(sql: string): Promise<void>;
|
|
20
|
+
/**
|
|
21
|
+
* Run `fn` inside a real transaction (`BEGIN [IMMEDIATE] ... COMMIT` /
|
|
22
|
+
* `ROLLBACK` on error). Same rationale as `execScript` above — declared on
|
|
23
|
+
* the concrete `SqliteAdapter`, not on the narrower `HazoConnectAdapter`
|
|
24
|
+
* interface.
|
|
25
|
+
*/
|
|
26
|
+
transaction<T>(fn: (tx: {
|
|
27
|
+
rawQuery: HazoConnectAdapter["rawQuery"];
|
|
28
|
+
execScript: (sql: string) => Promise<void>;
|
|
29
|
+
}) => Promise<T>, opts?: {
|
|
30
|
+
immediate?: boolean;
|
|
31
|
+
}): Promise<T>;
|
|
7
32
|
}
|
|
8
33
|
export declare function augmentAdapter(adapter: HazoConnectAdapter): AugmentedAdapter;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
export interface ScanTranslationUsageOptions {
|
|
2
|
+
/** File extensions to scan. Defaults to [".ts", ".tsx"]. */
|
|
3
|
+
extensions?: string[];
|
|
4
|
+
/** Directory names to skip while walking `srcDir`. */
|
|
5
|
+
ignoreDirs?: string[];
|
|
6
|
+
/**
|
|
7
|
+
* Catalog key patterns that are reached only via a computed/dynamic `t()`
|
|
8
|
+
* call (e.g. `t(\`faq.${i}.question\`)`), and must therefore be treated as
|
|
9
|
+
* "used" even though no literal call site references them. A trailing `*`
|
|
10
|
+
* matches any key sharing that dot-prefix, e.g. `"faq.*"` covers
|
|
11
|
+
* `faq.0.question`, `faq.1.answer`, etc. An exact entry (no `*`) matches
|
|
12
|
+
* only that one key.
|
|
13
|
+
*/
|
|
14
|
+
allowlist?: string[];
|
|
15
|
+
}
|
|
16
|
+
export interface ScanTranslationUsageResult {
|
|
17
|
+
/** Keys referenced by a literal `t("key")` call but absent from the catalog. */
|
|
18
|
+
missing: string[];
|
|
19
|
+
/** Catalog keys never referenced by a literal `t()` call and not covered by `allowlist`. */
|
|
20
|
+
unused: string[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Scans `srcDir` for literal `t("key")` call sites and diffs them against the
|
|
24
|
+
* flattened JSON catalog at `catalogPath`.
|
|
25
|
+
*
|
|
26
|
+
* @param srcDir - directory to walk recursively for `.ts`/`.tsx` source.
|
|
27
|
+
* @param catalogPath - path to a JSON message catalog (may be nested).
|
|
28
|
+
* @param options - extension filter, directory ignore list, and allowlist
|
|
29
|
+
* for keys reached only via computed/dynamic `t()` calls.
|
|
30
|
+
*/
|
|
31
|
+
export declare function scanTranslationUsage(srcDir: string, catalogPath: string, options?: ScanTranslationUsageOptions): ScanTranslationUsageResult;
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
// src/i18n/scan_translation_usage.ts
|
|
2
|
+
// Purpose: a static-analysis sanity check for hazo consumer apps that use a
|
|
3
|
+
// `t("some.key")` translation function (next-intl, hazo_core/i18n, etc.).
|
|
4
|
+
// Greps `.ts`/`.tsx` source for literal `t("key")` / `t('key')` call sites,
|
|
5
|
+
// flattens a JSON message catalog into dot-notation leaf keys, and diffs the
|
|
6
|
+
// two sets.
|
|
7
|
+
//
|
|
8
|
+
// Deliberately conservative:
|
|
9
|
+
// - Only LITERAL string-argument calls are matched (`t("a.b")`, `t('a.b')`).
|
|
10
|
+
// A dynamic call — `t(someVar)`, `t(\`a.${i}.b\`)` — has no string literal
|
|
11
|
+
// for the regex to capture, so it is silently skipped rather than
|
|
12
|
+
// misreported as a usage or a miss. Use `allowlist` to mark the catalog
|
|
13
|
+
// keys such calls are known to resolve to, so they are not reported as
|
|
14
|
+
// `unused`.
|
|
15
|
+
// - Node-only (`node:fs`). This module imports fs/path at module scope and
|
|
16
|
+
// is exported from the dedicated `hazo_testing/i18n` sub-path, not the
|
|
17
|
+
// browser-safe `hazo_testing/client` barrel.
|
|
18
|
+
import { readFileSync, readdirSync, statSync } from "node:fs";
|
|
19
|
+
import { join } from "node:path";
|
|
20
|
+
const DEFAULT_EXTENSIONS = [".ts", ".tsx"];
|
|
21
|
+
const DEFAULT_IGNORE_DIRS = new Set(["node_modules", ".next", "dist", "build", ".git"]);
|
|
22
|
+
/** Matches `t("key")` / `t('key')` — a literal single- or double-quoted first argument. */
|
|
23
|
+
const T_CALL_RE = /\bt\(\s*(["'])((?:\\.|(?!\1)[^\\\n])+)\1/g;
|
|
24
|
+
function walk(dir, extensions, ignoreDirs, out) {
|
|
25
|
+
let entries;
|
|
26
|
+
try {
|
|
27
|
+
entries = readdirSync(dir);
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
for (const entry of entries) {
|
|
33
|
+
const full = join(dir, entry);
|
|
34
|
+
let stat;
|
|
35
|
+
try {
|
|
36
|
+
stat = statSync(full);
|
|
37
|
+
}
|
|
38
|
+
catch {
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
if (stat.isDirectory()) {
|
|
42
|
+
if (ignoreDirs.has(entry))
|
|
43
|
+
continue;
|
|
44
|
+
walk(full, extensions, ignoreDirs, out);
|
|
45
|
+
}
|
|
46
|
+
else if (extensions.some((ext) => entry.endsWith(ext))) {
|
|
47
|
+
out.push(full);
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/** Recursively flattens a JSON catalog into dot-notation leaf keys. */
|
|
52
|
+
function flattenCatalog(value, prefix, out) {
|
|
53
|
+
if (value !== null && typeof value === "object" && !Array.isArray(value)) {
|
|
54
|
+
const obj = value;
|
|
55
|
+
const keys = Object.keys(obj);
|
|
56
|
+
if (keys.length === 0) {
|
|
57
|
+
if (prefix)
|
|
58
|
+
out.add(prefix);
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
for (const key of keys) {
|
|
62
|
+
const nextPrefix = prefix ? `${prefix}.${key}` : key;
|
|
63
|
+
flattenCatalog(obj[key], nextPrefix, out);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
else {
|
|
67
|
+
// Leaf (string, number, boolean, null, array) — this IS a usable key.
|
|
68
|
+
if (prefix)
|
|
69
|
+
out.add(prefix);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
function extractUsedKeys(filePath) {
|
|
73
|
+
const text = readFileSync(filePath, "utf-8");
|
|
74
|
+
const keys = [];
|
|
75
|
+
for (const match of text.matchAll(T_CALL_RE)) {
|
|
76
|
+
keys.push(match[2]);
|
|
77
|
+
}
|
|
78
|
+
return keys;
|
|
79
|
+
}
|
|
80
|
+
function isAllowlisted(key, allowlist) {
|
|
81
|
+
for (const pattern of allowlist) {
|
|
82
|
+
if (pattern.endsWith("*")) {
|
|
83
|
+
const prefix = pattern.slice(0, -1);
|
|
84
|
+
if (key.startsWith(prefix))
|
|
85
|
+
return true;
|
|
86
|
+
}
|
|
87
|
+
else if (key === pattern) {
|
|
88
|
+
return true;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return false;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Scans `srcDir` for literal `t("key")` call sites and diffs them against the
|
|
95
|
+
* flattened JSON catalog at `catalogPath`.
|
|
96
|
+
*
|
|
97
|
+
* @param srcDir - directory to walk recursively for `.ts`/`.tsx` source.
|
|
98
|
+
* @param catalogPath - path to a JSON message catalog (may be nested).
|
|
99
|
+
* @param options - extension filter, directory ignore list, and allowlist
|
|
100
|
+
* for keys reached only via computed/dynamic `t()` calls.
|
|
101
|
+
*/
|
|
102
|
+
export function scanTranslationUsage(srcDir, catalogPath, options = {}) {
|
|
103
|
+
const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
|
|
104
|
+
const ignoreDirs = options.ignoreDirs
|
|
105
|
+
? new Set(options.ignoreDirs)
|
|
106
|
+
: DEFAULT_IGNORE_DIRS;
|
|
107
|
+
const allowlist = options.allowlist ?? [];
|
|
108
|
+
const files = [];
|
|
109
|
+
walk(srcDir, extensions, ignoreDirs, files);
|
|
110
|
+
const usedKeys = new Set();
|
|
111
|
+
for (const file of files) {
|
|
112
|
+
for (const key of extractUsedKeys(file))
|
|
113
|
+
usedKeys.add(key);
|
|
114
|
+
}
|
|
115
|
+
const catalogRaw = readFileSync(catalogPath, "utf-8");
|
|
116
|
+
const catalog = JSON.parse(catalogRaw);
|
|
117
|
+
const catalogKeys = new Set();
|
|
118
|
+
flattenCatalog(catalog, "", catalogKeys);
|
|
119
|
+
const missing = [];
|
|
120
|
+
for (const key of usedKeys) {
|
|
121
|
+
if (!catalogKeys.has(key))
|
|
122
|
+
missing.push(key);
|
|
123
|
+
}
|
|
124
|
+
const unused = [];
|
|
125
|
+
for (const key of catalogKeys) {
|
|
126
|
+
if (!usedKeys.has(key) && !isAllowlisted(key, allowlist))
|
|
127
|
+
unused.push(key);
|
|
128
|
+
}
|
|
129
|
+
missing.sort();
|
|
130
|
+
unused.sort();
|
|
131
|
+
return { missing, unused };
|
|
132
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const HAZO_TESTING_VERSION = "0.
|
|
1
|
+
export declare const HAZO_TESTING_VERSION = "0.5.0";
|
|
2
2
|
export declare const t: import("hazo_core/i18n").TFunc;
|
|
3
3
|
export { DockerNotSupported, UnmappedLlmCall } from "./errors.js";
|
|
4
4
|
export { augmentAdapter } from "./db/augmented_adapter.js";
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// hazo_testing public server barrel.
|
|
3
3
|
import en from "./locales/en.json" with { type: "json" };
|
|
4
4
|
import { createPackageT } from "hazo_core/i18n";
|
|
5
|
-
export const HAZO_TESTING_VERSION = "0.
|
|
5
|
+
export const HAZO_TESTING_VERSION = "0.5.0";
|
|
6
6
|
// Module-scope translator — see hazo_core/i18n's createPackageT. hazo_testing
|
|
7
7
|
// is a zero-string package today (dev/test infra, no rendered UI text); this
|
|
8
8
|
// is future-proofing plumbing so a real catalog can be dropped in later
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** Resolve a peer specifier's absolute path, anchored to the consumer's cwd. */
|
|
2
|
+
export declare function resolve_peer_path(specifier: string): string;
|
|
3
|
+
/** Resolve then dynamically import a peer specifier, anchored to the consumer's cwd. */
|
|
4
|
+
export declare function import_peer<T = any>(specifier: string): Promise<T>;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// src/internal/resolve_peer.ts
|
|
2
|
+
// Purpose: resolve a bare peer specifier (e.g. "react", "@testing-library/react",
|
|
3
|
+
// "next-intl") starting module resolution from the CONSUMER's current working
|
|
4
|
+
// directory, not from this file's own on-disk location.
|
|
5
|
+
//
|
|
6
|
+
// Why this exists: hazo_testing is commonly consumed via a `file:` dependency
|
|
7
|
+
// pointing at a real directory that lives OUTSIDE the consumer's own
|
|
8
|
+
// node_modules tree (e.g. a sibling checkout in a local-packages monorepo —
|
|
9
|
+
// this is exactly how gotimer consumes it). Node's module resolution for a
|
|
10
|
+
// bare specifier imported from one of hazo_testing's own compiled files walks
|
|
11
|
+
// UP FROM THAT REAL ON-DISK PATH — which can find an unrelated copy of the
|
|
12
|
+
// peer hoisted in an ancestor node_modules (e.g. the monorepo workspace
|
|
13
|
+
// root), not the consumer's own installed copy. Two different module
|
|
14
|
+
// instances of "react" in one render tree breaks React's reconciliation
|
|
15
|
+
// ("Objects are not valid as a React child", invalid hook call, etc.) even
|
|
16
|
+
// though react/react-dom/@testing-library/react are all correctly declared
|
|
17
|
+
// as peerDependencies here — peerDependencies is an install-time contract,
|
|
18
|
+
// not a runtime resolution mechanism, and it can't steer Node's resolution
|
|
19
|
+
// across a `file:` link's realpath boundary.
|
|
20
|
+
//
|
|
21
|
+
// Anchoring resolution to `process.cwd()` (the consumer's own project root
|
|
22
|
+
// when its test runner invokes Jest/Vitest) guarantees we find the
|
|
23
|
+
// consumer's own installed copy instead. When hazo_testing runs its OWN
|
|
24
|
+
// tests, `process.cwd()` is hazo_testing's own directory, so resolution
|
|
25
|
+
// behaves exactly as before (same hoisted workspace copy it already used).
|
|
26
|
+
//
|
|
27
|
+
// We only use `createRequire(...).resolve()` to compute the path — the
|
|
28
|
+
// actual module is always loaded with a dynamic `import()`, per this
|
|
29
|
+
// package's "no require() for peer packages" convention (see CLAUDE.md).
|
|
30
|
+
import { createRequire } from "node:module";
|
|
31
|
+
import path from "node:path";
|
|
32
|
+
const consumer_require = createRequire(path.join(process.cwd(), "__hazo_testing_peer_resolve__.cjs"));
|
|
33
|
+
/** Resolve a peer specifier's absolute path, anchored to the consumer's cwd. */
|
|
34
|
+
export function resolve_peer_path(specifier) {
|
|
35
|
+
return consumer_require.resolve(specifier);
|
|
36
|
+
}
|
|
37
|
+
/** Resolve then dynamically import a peer specifier, anchored to the consumer's cwd. */
|
|
38
|
+
export async function import_peer(specifier) {
|
|
39
|
+
return (await import(resolve_peer_path(specifier)));
|
|
40
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import React from "react";
|
|
1
|
+
import type React from "react";
|
|
2
2
|
export interface RenderWithIntlOptions {
|
|
3
3
|
/** BCP-47 locale passed to NextIntlClientProvider. Defaults to "en". */
|
|
4
4
|
locale?: string;
|
|
@@ -9,6 +9,7 @@ export interface RenderWithIntlOptions {
|
|
|
9
9
|
}
|
|
10
10
|
/**
|
|
11
11
|
* Render `ui` inside a NextIntlClientProvider. Returns the
|
|
12
|
-
* `@testing-library/react` RenderResult.
|
|
12
|
+
* `@testing-library/react` RenderResult. All three peers are resolved lazily
|
|
13
|
+
* from the consumer's own installed copies.
|
|
13
14
|
*/
|
|
14
15
|
export declare function renderWithIntl(ui: React.ReactElement, options?: RenderWithIntlOptions): Promise<unknown>;
|
package/dist/render_with_intl.js
CHANGED
|
@@ -1,14 +1,23 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { import_peer } from "./internal/resolve_peer.js";
|
|
2
2
|
/**
|
|
3
3
|
* Render `ui` inside a NextIntlClientProvider. Returns the
|
|
4
|
-
* `@testing-library/react` RenderResult.
|
|
4
|
+
* `@testing-library/react` RenderResult. All three peers are resolved lazily
|
|
5
|
+
* from the consumer's own installed copies.
|
|
5
6
|
*/
|
|
6
7
|
export async function renderWithIntl(ui, options = {}) {
|
|
7
8
|
const { locale = "en", messages = {}, renderOptions } = options;
|
|
9
|
+
let react_ns;
|
|
10
|
+
try {
|
|
11
|
+
const react_mod = await import_peer("react");
|
|
12
|
+
react_ns = react_mod.default ?? react_mod;
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
throw new Error("renderWithIntl requires the peer dependency `react` to be installed.");
|
|
16
|
+
}
|
|
8
17
|
let NextIntlClientProvider;
|
|
9
18
|
try {
|
|
10
19
|
// optional peer — `next-intl` may not be installed at runtime
|
|
11
|
-
({ NextIntlClientProvider } = await
|
|
20
|
+
({ NextIntlClientProvider } = await import_peer("next-intl"));
|
|
12
21
|
}
|
|
13
22
|
catch {
|
|
14
23
|
throw new Error("renderWithIntl requires the optional peer dependency `next-intl` to be installed.");
|
|
@@ -16,11 +25,11 @@ export async function renderWithIntl(ui, options = {}) {
|
|
|
16
25
|
let render;
|
|
17
26
|
try {
|
|
18
27
|
// optional peer — `@testing-library/react` may not be installed at runtime
|
|
19
|
-
({ render } = await
|
|
28
|
+
({ render } = await import_peer("@testing-library/react"));
|
|
20
29
|
}
|
|
21
30
|
catch {
|
|
22
31
|
throw new Error("renderWithIntl requires the optional peer dependency `@testing-library/react` to be installed.");
|
|
23
32
|
}
|
|
24
|
-
const wrapped = (
|
|
33
|
+
const wrapped = react_ns.createElement(NextIntlClientProvider, { locale, messages }, ui);
|
|
25
34
|
return render(wrapped, renderOptions);
|
|
26
35
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hazo_testing",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.2",
|
|
4
4
|
"description": "Shared test infrastructure for hazo apps: SQLite test DB, real-package wiring, auth factories, apiTestClient, fixtures, Jest + Vitest presets.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -60,6 +60,14 @@
|
|
|
60
60
|
"./nextjs": {
|
|
61
61
|
"types": "./dist/nextjs/index.d.ts",
|
|
62
62
|
"default": "./dist/nextjs/index.js"
|
|
63
|
+
},
|
|
64
|
+
"./audio": {
|
|
65
|
+
"types": "./dist/audio/audio_stub.d.ts",
|
|
66
|
+
"default": "./dist/audio/audio_stub.js"
|
|
67
|
+
},
|
|
68
|
+
"./i18n": {
|
|
69
|
+
"types": "./dist/i18n/scan_translation_usage.d.ts",
|
|
70
|
+
"default": "./dist/i18n/scan_translation_usage.js"
|
|
63
71
|
}
|
|
64
72
|
},
|
|
65
73
|
"files": [
|
|
@@ -85,15 +93,15 @@
|
|
|
85
93
|
"peerDependencies": {
|
|
86
94
|
"@playwright/test": "^1.0.0",
|
|
87
95
|
"@testing-library/react": "^16.0.0",
|
|
88
|
-
"hazo_auth": "^10.
|
|
89
|
-
"hazo_connect": "^4.3.
|
|
96
|
+
"hazo_auth": "^10.23.3",
|
|
97
|
+
"hazo_connect": "^4.3.2",
|
|
90
98
|
"hazo_core": "^2.4.0",
|
|
91
|
-
"hazo_i18n": "^0.
|
|
99
|
+
"hazo_i18n": "^0.9.0",
|
|
92
100
|
"hazo_jobs": "^0.19.0",
|
|
93
101
|
"hazo_llm_api": "^2.6.0",
|
|
94
|
-
"hazo_notify": "^6.
|
|
102
|
+
"hazo_notify": "^6.7.0",
|
|
95
103
|
"next": "^14.0.0 || ^16.0.0",
|
|
96
|
-
"next-intl": "^4.
|
|
104
|
+
"next-intl": "^4.13.0",
|
|
97
105
|
"react": "^18.0.0 || ^19.0.0",
|
|
98
106
|
"react-dom": "^18.0.0 || ^19.0.0",
|
|
99
107
|
"vitest": "^2.0.0 || ^3.0.0"
|
package/vitest-preset.mjs
CHANGED
|
@@ -31,6 +31,19 @@ export default function vitestPreset(options = {}) {
|
|
|
31
31
|
environment: "node",
|
|
32
32
|
setupFiles: ["hazo_testing/vitest-setup", ...setupFiles],
|
|
33
33
|
testTimeout: 10000,
|
|
34
|
+
// hazo_* packages ship ESM/CJS dual builds; Vite must inline-transform
|
|
35
|
+
// them rather than externalising, or their sub-path exports break.
|
|
36
|
+
// NOTE: this lives under `test.server.deps.inline`, NOT a top-level
|
|
37
|
+
// `server` key. A top-level `server` collides with Vite's own
|
|
38
|
+
// `ServerOptions` (e.g. dev-server `server.fs.allow`) and breaks
|
|
39
|
+
// `tsc --noEmit` for any consumer that spreads this factory's return
|
|
40
|
+
// value into `defineConfig` and also sets real `server` options
|
|
41
|
+
// (fixed in 0.5.0 — was previously mis-nested at the top level).
|
|
42
|
+
server: {
|
|
43
|
+
deps: {
|
|
44
|
+
inline: [/hazo_/],
|
|
45
|
+
},
|
|
46
|
+
},
|
|
34
47
|
},
|
|
35
48
|
resolve: {
|
|
36
49
|
alias: {
|
|
@@ -38,12 +51,5 @@ export default function vitestPreset(options = {}) {
|
|
|
38
51
|
...alias,
|
|
39
52
|
},
|
|
40
53
|
},
|
|
41
|
-
server: {
|
|
42
|
-
// hazo_* packages ship ESM/CJS dual builds; Vite must inline-transform
|
|
43
|
-
// them rather than externalising, or their sub-path exports break.
|
|
44
|
-
deps: {
|
|
45
|
-
inline: [/hazo_/],
|
|
46
|
-
},
|
|
47
|
-
},
|
|
48
54
|
};
|
|
49
55
|
}
|