@zyplux/spectra 0.3.1 → 0.4.0

package/README.md

@@ -58,6 +58,7 @@ Each tool has a named entry point. Import the Vitest bases from `/library-test-a
 | --- | --- |
 | `/library-test-api` | Library and CLI Vitest bases |
 | `/shell-fake`, `/fetch-fake`, `/prompt-fake` | Fakes for subprocesses, HTTP, and prompts |
+| `/repository-fake`, `/repository-test` | Git/GitHub command replies and repository-aware CLI fixtures |
 | `/cli-runner`, `/temp-directory`, `/poll-until` | CLI execution, scratch directories, and test polling |
 | `/test-matchers` | Register shared Vitest matchers |
 | `/console-capture` | Capture console messages |
@@ -70,10 +71,12 @@ Internal helpers stay beside the tools that use them: pattern matching and modul
 
 - `libraryTest` — lazy fixtures: `shell` (fake `node:child_process` spawn, installed only when destructured), `tempDir` (auto-removed scratch directory with `path`, `write`, `exists`).
 - `cliTest` — extends `libraryTest`; automatically captures and silences `console` (`logs`), makes `node:timers/promises` sleeps instant, and installs `network` (fake `fetch`). It adds lazy `prompt` (fake `node:readline/promises` interface that records every question and answers with an empty string) and `env` (`set(name, value)` stubs an env var for the test).
+- `repositoryTest` — extends `cliTest` with a lazy `repo` fake and the mocked timer function as `sleep` for polling assertions.
 
 ## Fakes and helpers
 
 - `createShellFake()` — routes commands (`on(pattern, ...replies)`, later routes win, the last reply repeats; `otherwise(reply)` sets a fallback, unrouted commands throw) and records `calls` (`{ argv, cwd?, env?, program, stdin? }`), `commands` (rendered strings), `commandsMatching(pattern)`.
+- `createRepositoryFake(shell, rootPath)` — configures Git/GitHub replies for branches, commits, PRs and repository identity. Common repository writes succeed by default; override their shell replies to test failures.
 - `createConsoleCapture()` — records `logLines`/`warnLines`/`errorLines`.
 - `createFetchFake()` — routes urls (`on(prefixOrRegExp, reply)`, `otherwise(reply)`) and records `requests`; `okResponse()`/`notFoundResponse()` build replies.
 - `createPromptFake()` — records `question()` messages and immediately returns an empty string, simulating Enter without typed input. It lets tests exercise terminal prompts without waiting for keyboard input.

package/dist/fakes/repository-fake.d.ts

@@ -0,0 +1,27 @@
+import type { ShellFake } from './shell-fake.ts';
+export type RepositoryFake = {
+    queuePrFields: (fields: Record<string, [boolean | number | string, ...(boolean | number | string)[]] | boolean | number | string>) => void;
+    setCurrentBranch: (branch: string) => void;
+    setHeadSha: (sha: string) => void;
+    setPrListState: (state: string) => void;
+    setRemoteBranchSha: (branch: string, ...shas: [string, ...string[]]) => void;
+    setRemoteMainSha: (sha: string) => void;
+    setRepoSlug: (slug: string) => void;
+    setRoot: (dir: string) => void;
+    setWorkingTreeStatus: (status: string) => void;
+    syncFeatureBranch: (branch: string, sha: string) => void;
+    syncMain: (sha: string) => void;
+};
+export declare const createRepositoryFake: (shell: ShellFake, rootPath: string) => {
+    queuePrFields: (fields: Record<string, string | number | boolean | [string | number | boolean, ...(string | number | boolean)[]]>) => void;
+    setCurrentBranch: (branch: string) => void;
+    setHeadSha: (sha: string) => void;
+    setPrListState: (state: string) => void;
+    setRemoteBranchSha: (branch: string, shas_0: string, ...shas: string[]) => void;
+    setRemoteMainSha: (sha: string) => void;
+    setRepoSlug: (slug: string) => void;
+    setRoot: (dir: string) => void;
+    setWorkingTreeStatus: (status: string) => void;
+    syncFeatureBranch: (branch: string, sha: string) => void;
+    syncMain: (sha: string) => void;
+};

package/dist/fakes/repository-fake.js

@@ -0,0 +1,68 @@
+const BENIGN_WRITE_COMMANDS = [
+    'gh pr create',
+    'gh pr merge',
+    'gh pr ready',
+    'gh release create',
+    'gh release delete',
+    'git branch',
+    'git checkout',
+    'git fetch',
+    'git pull',
+    'git push',
+];
+export const createRepositoryFake = (shell, rootPath) => {
+    const setRoot = (dir) => {
+        shell.on('git rev-parse --show-toplevel', dir);
+    };
+    setRoot(rootPath);
+    for (const command of BENIGN_WRITE_COMMANDS)
+        shell.on(command, '');
+    const setCurrentBranch = (branch) => {
+        shell.on('git rev-parse --abbrev-ref HEAD', branch);
+    };
+    const setHeadSha = (sha) => {
+        shell.on('git rev-parse HEAD', sha);
+    };
+    const setRemoteMainSha = (sha) => {
+        shell.on('git rev-parse origin/main', sha);
+    };
+    const setWorkingTreeStatus = (status) => {
+        shell.on('git status --porcelain', status);
+    };
+    const setRemoteBranchSha = (branch, ...shas) => {
+        const [firstSha, ...laterShas] = shas;
+        const toRefLine = (sha) => `${sha}\trefs/heads/${branch}`;
+        shell.on(`git ls-remote origin refs/heads/${branch}`, toRefLine(firstSha), ...laterShas.map(sha => toRefLine(sha)));
+    };
+    return {
+        queuePrFields: fields => {
+            for (const [field, values] of Object.entries(fields)) {
+                const [first, ...later] = Array.isArray(values) ? values : [values];
+                shell.on(`gh pr view --json ${field}`, JSON.stringify({ [field]: first }), ...later.map(value => JSON.stringify({ [field]: value })));
+            }
+        },
+        setCurrentBranch,
+        setHeadSha,
+        setPrListState: state => {
+            shell.on('gh pr list', JSON.stringify(state ? [{ state }] : []));
+        },
+        setRemoteBranchSha,
+        setRemoteMainSha,
+        setRepoSlug: slug => {
+            shell.on('gh repo view --json nameWithOwner', JSON.stringify({ nameWithOwner: slug }));
+        },
+        setRoot,
+        setWorkingTreeStatus,
+        syncFeatureBranch: (branch, sha) => {
+            setCurrentBranch(branch);
+            setHeadSha(sha);
+            setRemoteBranchSha(branch, sha);
+        },
+        syncMain: sha => {
+            setCurrentBranch('main');
+            setHeadSha(sha);
+            setRemoteMainSha(sha);
+            setWorkingTreeStatus('');
+        },
+    };
+};

package/dist/repository-test.d.ts

@@ -0,0 +1,16 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import type { RepositoryFake } from './fakes/repository-fake.ts';
+export declare const repositoryTest: import("vitest").TestAPI<{
+    prompt: import("./fakes/prompt-fake.ts").PromptFake;
+    shell: import("./fakes/shell-fake.ts").ShellFake;
+    tempDir: import("./helpers/temp-directory.ts").TempDir;
+    env: import("./library-test-api.ts").EnvStub;
+    instantSleep: undefined;
+    logs: import("./reporters/console-capture.ts").ConsoleCapture;
+    network: import("./fakes/fetch-fake.ts").FetchFake;
+    sleep: typeof sleep;
+    $__test: (object & Record<"sleep", typeof sleep>) | undefined;
+    repo: RepositoryFake;
+    $__worker: object | undefined;
+    $__file: object | undefined;
+}>;

package/dist/repository-test.js

@@ -0,0 +1,10 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { createRepositoryFake } from "./fakes/repository-fake.js";
+import { cliTest } from "./library-test-api.js";
+export const repositoryTest = cliTest
+    .extend('sleep', () => sleep)
+    .extend({
+    repo: async ({ shell, tempDir }, use) => {
+        await use(createRepositoryFake(shell, tempDir.path));
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyplux/spectra",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shared Vitest fixtures, matchers, polling, and journal reporting.",
   "keywords": [
     "test",
@@ -59,7 +59,15 @@
       "types": "./dist/reporters/journald-reporter.d.ts",
       "default": "./dist/reporters/journald-reporter.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./repository-fake": {
+      "types": "./dist/fakes/repository-fake.d.ts",
+      "default": "./dist/fakes/repository-fake.js"
+    },
+    "./repository-test": {
+      "types": "./dist/repository-test.d.ts",
+      "default": "./dist/repository-test.js"
+    }
   },
   "files": [
     "README.md",
@@ -69,13 +77,13 @@
     "access": "public"
   },
   "peerDependencies": {
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
-    "@zyplux/tsconfig": "0.3.1",
+    "@types/node": "^26.6.5",
+    "@zyplux/tsconfig": "0.3.3",
     "publint": "^0.3.25",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   },
   "imports": {
     "#pattern-match": "./dist/helpers/pattern-match.js",