hazo_testing 0.4.0 → 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 CHANGED
@@ -1,5 +1,145 @@
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
+
122
+ ## 0.4.1 — 2026-09-19
123
+
124
+ ### Added — i18n future-proofing plumbing (no behavior change)
125
+
126
+ hazo_testing is a zero-string package today (dev/test infra — no rendered
127
+ UI text; the only string literals are internal `HazoError` codes/messages
128
+ for developers). Verified this during adoption and made no call-site
129
+ changes. Added minimal plumbing so a real catalog can be dropped in later
130
+ without touching consumers:
131
+
132
+ - `src/locales/en.json` — empty flat catalog (`{}`).
133
+ - `t` export (both `.` and `./client` entry points) wired through the
134
+ canonical `createPackageT` bridge from `hazo_core/i18n`.
135
+ - `hazo_i18n` added as an optional peer dependency (`^0.5.0`) — this
136
+ package never imports it directly; `hazo_core/i18n` probes for it at
137
+ runtime and registers the (currently empty) catalog as a side effect if
138
+ present.
139
+ - Autotest: added an `i18n` scenario group to the test-app's
140
+ `/autotest` page asserting `typeof t === 'function'` from
141
+ `hazo_testing/client`.
142
+
3
143
  ## 0.4.0 — 2026-08-04
4
144
 
5
145
  ### Fixed
@@ -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
- }): import("react/jsx-runtime").JSX.Element;
19
+ }): React.FunctionComponentElement<React.ProviderProps<TestCtxValue>>;
20
20
  export {};
@@ -1,10 +1,8 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
2
- // src/components/test_providers.tsx
3
- // Purpose: lightweight provider wrapper for component tests. Exposes a test
4
- // user + scope via context; deeper hazo_auth context wiring is deferred.
5
- import { createContext, useContext } from "react";
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 _jsx(TestCtx.Provider, { value: { user: props.user, scope: props.scope }, children: props.children });
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
+ }
@@ -1,2 +1,3 @@
1
1
  export { TestProviders, useTestContext } from "./components/test_providers.js";
2
2
  export type { TestUserCtx, TestScopeCtx } from "./components/test_providers.js";
3
+ export declare const t: import("hazo_core/i18n").TFunc;
@@ -1,3 +1,11 @@
1
1
  // src/index.client.ts
2
2
  // Purpose: client-safe barrel (no Node imports).
3
+ import en from "./locales/en.json" with { type: "json" };
4
+ import { createPackageT } from "hazo_core/i18n";
3
5
  export { TestProviders, useTestContext } from "./components/test_providers.js";
6
+ // Module-scope translator — see hazo_core/i18n's createPackageT. hazo_testing
7
+ // is a zero-string package today (no rendered UI text); this is
8
+ // future-proofing plumbing so a real catalog can be dropped in later without
9
+ // touching call sites. English-only consumers (no hazo_i18n installed) see
10
+ // no behavior change.
11
+ export const t = createPackageT("hazo_testing", en);
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- export declare const HAZO_TESTING_VERSION = "0.3.0";
1
+ export declare const HAZO_TESTING_VERSION = "0.5.0";
2
+ export declare const t: import("hazo_core/i18n").TFunc;
2
3
  export { DockerNotSupported, UnmappedLlmCall } from "./errors.js";
3
4
  export { augmentAdapter } from "./db/augmented_adapter.js";
4
5
  export type { AugmentedAdapter } from "./db/augmented_adapter.js";
package/dist/index.js CHANGED
@@ -1,6 +1,14 @@
1
1
  // src/index.ts
2
2
  // hazo_testing public server barrel.
3
- export const HAZO_TESTING_VERSION = "0.3.0";
3
+ import en from "./locales/en.json" with { type: "json" };
4
+ import { createPackageT } from "hazo_core/i18n";
5
+ export const HAZO_TESTING_VERSION = "0.5.0";
6
+ // Module-scope translator — see hazo_core/i18n's createPackageT. hazo_testing
7
+ // is a zero-string package today (dev/test infra, no rendered UI text); this
8
+ // is future-proofing plumbing so a real catalog can be dropped in later
9
+ // without touching call sites. English-only consumers (no hazo_i18n
10
+ // installed) see no behavior change.
11
+ export const t = createPackageT("hazo_testing", en);
4
12
  export { DockerNotSupported, UnmappedLlmCall } from "./errors.js";
5
13
  export { augmentAdapter } from "./db/augmented_adapter.js";
6
14
  export { createTestDatabase, createTestDatabaseSqlite, createTestDatabaseDocker, } from "./db/test_database.js";
@@ -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
+ }
@@ -0,0 +1 @@
1
+ {}
@@ -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. Both peers are resolved lazily.
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>;
@@ -1,14 +1,23 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
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. Both peers are resolved lazily.
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 import("next-intl"));
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 import("@testing-library/react"));
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 = (_jsx(NextIntlClientProvider, { locale: locale, messages: messages, children: ui }));
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.4.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,14 +93,15 @@
85
93
  "peerDependencies": {
86
94
  "@playwright/test": "^1.0.0",
87
95
  "@testing-library/react": "^16.0.0",
88
- "hazo_auth": "^10.15.0",
89
- "hazo_connect": "^4.0.0",
90
- "hazo_core": "^2.0.0",
91
- "hazo_jobs": "^0.17.0",
92
- "hazo_llm_api": "^2.3.0",
93
- "hazo_notify": "^6.1.5",
96
+ "hazo_auth": "^10.23.3",
97
+ "hazo_connect": "^4.3.2",
98
+ "hazo_core": "^2.4.0",
99
+ "hazo_i18n": "^0.9.0",
100
+ "hazo_jobs": "^0.19.0",
101
+ "hazo_llm_api": "^2.6.0",
102
+ "hazo_notify": "^6.7.0",
94
103
  "next": "^14.0.0 || ^16.0.0",
95
- "next-intl": "^4.0.0",
104
+ "next-intl": "^4.13.0",
96
105
  "react": "^18.0.0 || ^19.0.0",
97
106
  "react-dom": "^18.0.0 || ^19.0.0",
98
107
  "vitest": "^2.0.0 || ^3.0.0"
@@ -112,6 +121,9 @@
112
121
  },
113
122
  "react-dom": {
114
123
  "optional": true
124
+ },
125
+ "hazo_i18n": {
126
+ "optional": true
115
127
  }
116
128
  },
117
129
  "devDependencies": {
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
  }