@gate-forge/core 0.1.0

package/dist/testing/red-probe.js

@@ -0,0 +1,251 @@
+/**
+ * RED-PROBE discipline (fixture harness, G7): a green suite proves
+ * nothing unless the same guard FAILS against deliberately broken
+ * behavior. Every gate/fixture guard ships as a probe pair — the guard
+ * against correct behavior (must pass) and the identical guard against a
+ * deliberately broken variant (must fail) — and a broken probe that
+ * PASSES is a fake green: the loudest possible failure.
+ *
+ * Suite-level proof (CI-proof mode) runs the actual vitest suite twice —
+ * normal vs deliberately-broken sources — via {@link spawnVitest} and
+ * {@link writeProbeSuite}; the broken run must exit non-zero. See
+ * `docs/testing/RED_PROBE.md` for the per-phase recording discipline.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Thrown by {@link runRedProbe} when a probe is not honest. */
+export class RedProbeFailure extends Error {
+    /** The failing record. */
+    record;
+    constructor(record) {
+        super(record.failure ?? `red-probe '${record.name}' is not honest`);
+        this.name = 'RedProbeFailure';
+        this.record = record;
+    }
+}
+/**
+ * Runs one probe pair and classifies the outcome.
+ *
+ * Args:
+ *   probe: the green/broken guard pair.
+ *
+ * Returns:
+ *   RedProbeRecord: the classified outcome (never throws).
+ */
+export async function runRedProbe(probe) {
+    let greenPassed = true;
+    let greenError;
+    try {
+        await probe.green();
+    }
+    catch (error) {
+        greenPassed = false;
+        greenError = error;
+    }
+    let brokenFailed = false;
+    let brokenError;
+    try {
+        await probe.broken();
+    }
+    catch (error) {
+        brokenFailed = true;
+        brokenError = error;
+    }
+    const record = {
+        name: probe.name,
+        greenPassed,
+        brokenFailed,
+        ok: greenPassed && brokenFailed,
+    };
+    if (!greenPassed) {
+        record.failure =
+            `guard FAILS on correct behavior (the guard itself is broken): ${errorMessage(greenError)}`;
+    }
+    else if (!brokenFailed) {
+        record.failure =
+            `FAKE GREEN: the guard passed against deliberately broken behavior — it asserts nothing. ${errorMessage(brokenError)}`;
+    }
+    return record;
+}
+/**
+ * Extracts a one-line message from a thrown value.
+ *
+ * Args:
+ *   error: anything thrown.
+ *
+ * Returns:
+ *   string: the message, or a fallback description.
+ */
+function errorMessage(error) {
+    if (error === undefined)
+        return '(no error thrown)';
+    if (error instanceof Error)
+        return error.message.split('\n')[0] ?? error.message;
+    return String(error);
+}
+/** Thrown by {@link runRedProbes} when any probe is not honest. */
+export class RedProbeSuiteError extends Error {
+    /** All records, honest or not. */
+    records;
+    constructor(records) {
+        const bad = records.filter((record) => !record.ok);
+        super(`red-probe suite FAILED: ${bad.length} of ${records.length} probe(s) are fake-green or broken guards\n` +
+            bad.map((record) => `  - ${record.name}: ${record.failure}`).join('\n'));
+        this.name = 'RedProbeSuiteError';
+        this.records = records;
+    }
+}
+/**
+ * Runs probes sequentially and throws {@link RedProbeSuiteError} when any
+ * is not honest (pass `{throwOnFailure: false}` to only collect).
+ *
+ * Args:
+ *   probes: probe pairs, run in order.
+ *   options: `throwOnFailure` default true.
+ *
+ * Returns:
+ *   RedProbeRecord[]: one record per probe, in order.
+ */
+export async function runRedProbes(probes, { throwOnFailure = true } = {}) {
+    const records = [];
+    for (const probe of probes) {
+        records.push(await runRedProbe(probe));
+    }
+    if (throwOnFailure && records.some((record) => !record.ok)) {
+        throw new RedProbeSuiteError(records);
+    }
+    return records;
+}
+/**
+ * Renders probe records as a markdown table — the body of a run record.
+ *
+ * Args:
+ *   records: probe outcomes.
+ *
+ * Returns:
+ *   string: markdown table (probe / green passed / broken failed / verdict).
+ */
+export function formatProbeRecords(records) {
+    const rows = records.map((record) => `| ${record.name} | ${record.greenPassed ? 'yes' : 'NO'} | ${record.brokenFailed ? 'yes' : 'NO'} | ${record.ok ? 'ok' : 'FAKE GREEN / BROKEN GUARD'} |`);
+    return [
+        '| probe | green passed | broken failed | verdict |',
+        '| --- | --- | --- | --- |',
+        ...rows,
+        '',
+    ].join('\n');
+}
+/**
+ * Writes a red-probe run record (markdown) to an explicit file path,
+ * creating parent directories. The path is caller-owned so the harness
+ * never writes outside its permission.
+ *
+ * Args:
+ *   path: destination file path.
+ *   records: probe outcomes to record.
+ */
+export function writeProbeRecords(path, records) {
+    mkdirSync(dirname(path), { recursive: true });
+    const stamp = new Date().toISOString();
+    const header = `# Red-probe run record\n\nRecorded: ${stamp}\n\n`;
+    writeFileSync(path, header + formatProbeRecords(records), 'utf8');
+}
+/** The absolute path of the workspace's `node_modules/vitest/vitest.mjs`. */
+let cachedVitestCli;
+/**
+ * Locates the vitest CLI by walking up from this module to the nearest
+ * `node_modules` that contains vitest (works under npm workspaces
+ * hoisting regardless of package layout).
+ *
+ * Returns:
+ *   string: absolute path to vitest's CLI entry.
+ * @throws Error when vitest cannot be found above this module.
+ */
+function vitestCliPath() {
+    if (cachedVitestCli !== undefined)
+        return cachedVitestCli;
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(directory, 'node_modules', 'vitest', 'vitest.mjs');
+        if (existsSync(candidate)) {
+            cachedVitestCli = candidate;
+            return candidate;
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new Error('vitest installation not found above the testing harness');
+        }
+        directory = parent;
+    }
+}
+/**
+ * Runs the workspace's vitest suite as a child process (`vitest run`),
+ * fully offline. CI-proof mode runs a probe suite twice — normal vs
+ * deliberately-broken sources — and requires the broken run to exit
+ * non-zero.
+ *
+ * Args:
+ *   args: extra CLI arguments (file filters, --config, …).
+ *   options: cwd, env additions, timeout.
+ *
+ * Returns:
+ *   VitestRunResult: exit code and captured output.
+ */
+export function spawnVitest(args, options = {}) {
+    const result = spawnSync(process.execPath, [vitestCliPath(), 'run', ...args], {
+        cwd: options.cwd,
+        env: { ...process.env, ...options.env, CI: '1' },
+        timeout: options.timeoutMs ?? 120_000,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return {
+        exitCode: result.status ?? -1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        timedOut: result.signal === 'SIGTERM',
+    };
+}
+/**
+ * Materializes a probe suite in a directory and symlinks the workspace's
+ * `node_modules` into it, so probe files can `import ... from 'vitest'`
+ * even though the directory lives in the OS tmpdir. Clean up with
+ * `rmSync(dir, {recursive: true, force: true})` — removing the symlink
+ * never traverses into the real node_modules.
+ *
+ * Args:
+ *   dir: target directory (created recursively).
+ *   files: file-tree spec relative to `dir` (e.g. a `vitest.config.mjs`
+ *     exporting a plain object and one or more `*.test.mjs` probes).
+ *
+ * Returns:
+ *   string: the directory, ready for {@link spawnVitest} with `cwd: dir`.
+ */
+export function writeProbeSuite(dir, files) {
+    mkdirSync(dir, { recursive: true });
+    for (const [relative, content] of Object.entries(files)) {
+        const absolute = join(dir, ...relative.split('/'));
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, content, 'utf8');
+    }
+    const link = join(dir, 'node_modules');
+    if (!existsSync(link)) {
+        symlinkSync(dirname(vitestCliPath()), link, 'dir');
+    }
+    return dir;
+}
+/** Test-only: drops the cached vitest CLI path (path resolution tests). */
+export function resetVitestCliCache() {
+    cachedVitestCli = undefined;
+}
+/**
+ * Removes a probe-suite directory created by {@link writeProbeSuite}.
+ *
+ * Args:
+ *   dir: directory to remove.
+ */
+export function cleanupProbeSuite(dir) {
+    rmSync(dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=red-probe.js.map

package/dist/testing/red-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"red-probe.js","sourceRoot":"","sources":["../../src/testing/red-probe.ts"],"names":[],"mappings":"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"}

package/dist/testing/temp-repo.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The fixed timestamp (git raw-date form) stamped onto every commit as
+ * both author and committer date. Determinism cornerstone: change it and
+ * every fixture SHA changes.
+ */
+export declare const FIXED_GIT_DATE = "2026-01-01T00:00:00+0000";
+/** Result of one git invocation. */
+export interface GitResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+/** Options for {@link TempRepo} construction. */
+export interface TempRepoOptions {
+    /** Files written before the first command runs (repo-root-relative, posix keys). */
+    files?: Record<string, string>;
+    /** Initial branch name. Default `main`. */
+    branch?: string;
+    /** tmpdir prefix. Default `gateforge-fixture-`. */
+    prefix?: string;
+}
+/**
+ * A disposable git repository under the OS tmpdir.
+ *
+ * Args:
+ *   options: optional initial file tree, branch name, and tmpdir prefix.
+ *
+ * Returns:
+ *   TempRepo: use `writeFiles`/`stage`/`commit` to build history,
+ *   `cleanup` (or {@link withTempRepo}) to remove it.
+ */
+export declare class TempRepo {
+    /** Absolute filesystem path of the repository root. */
+    readonly root: string;
+    private readonly gitEnv;
+    constructor(options?: TempRepoOptions);
+    /**
+     * Runs one git command in the repository.
+     *
+     * Args:
+     *   args: argument vector (without the `git` binary).
+     *   allowFailure: when true a non-zero exit does not throw.
+     *
+     * Returns:
+     *   GitResult: exit status plus captured stdout/stderr.
+     * @throws Error naming the failing command when `allowFailure` is false.
+     */
+    git(args: string[], { allowFailure }?: {
+        allowFailure?: boolean;
+    }): GitResult;
+    /**
+     * Writes a file-tree spec into the repository. Keys are
+     * repo-root-relative posix paths; parent directories are created.
+     *
+     * Args:
+     *   files: mapping of relative posix path to UTF-8 file content.
+     * @throws Error on absolute paths or `..` segments (spec writers must
+     *   stay inside the repo).
+     */
+    writeFiles(files: Record<string, string>): void;
+    /**
+     * Stages files. With no argument stages every change (`git add -A`).
+     *
+     * Args:
+     *   paths: repo-root-relative paths to stage.
+     */
+    stage(paths?: string[]): void;
+    /**
+     * Commits the staged tree with a fixed identity and date.
+     *
+     * Args:
+     *   message: commit message.
+     * Returns:
+     *   string: the resulting HEAD sha (40-char hex).
+     */
+    commit(message: string): string;
+    /**
+     * Writes files, stages everything, and commits — the common fixture beat.
+     *
+     * Args:
+     *   files: file-tree spec to write before staging.
+     *   message: commit message.
+     * Returns:
+     *   string: the resulting HEAD sha.
+     */
+    commitFiles(files: Record<string, string>, message: string): string;
+    /**
+     * Reads the current HEAD sha.
+     *
+     * Returns:
+     *   string | null: 40-char hex sha, or null while the branch is unborn.
+     */
+    headSha(): string | null;
+    /**
+     * Lists currently staged (index vs HEAD) files — what the real
+     * `local-staged` changed-file provider would report (pin #5).
+     *
+     * Returns:
+     *   string[]: repo-root-relative posix paths (possibly empty).
+     */
+    stagedFiles(): string[];
+    /**
+     * Resolves a repo-root-relative posix path to an absolute path.
+     *
+     * Args:
+     *   relativePath: posix path relative to the repository root.
+     */
+    path(relativePath: string): string;
+    /**
+     * Removes the repository. Idempotent; safe to call more than once.
+     */
+    cleanup(): void;
+}
+/**
+ * Runs a fixture body against a fresh {@link TempRepo}, cleaning up on
+ * every path (sync throw, async rejection, success).
+ *
+ * Args:
+ *   options: TempRepo construction options.
+ *   body: receives the repo; may be async.
+ *
+ * Returns:
+ *   The body's return value (awaited when async).
+ */
+export declare function withTempRepo<T>(options: TempRepoOptions, body: (repo: TempRepo) => T): T | Promise<T>;
+//# sourceMappingURL=temp-repo.d.ts.map

package/dist/testing/temp-repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-repo.d.ts","sourceRoot":"","sources":["../../src/testing/temp-repo.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAiBzD,oCAAoC;AACpC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IACnB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,OAAO,GAAE,eAAoB;IAgBzC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAoB,EAAE,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,SAAS;IAoBzF;;;;;;;;OAQG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAY/C;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IAI7B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAO/B;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAMnE;;;;;OAKG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAKxB;;;;;;OAMG;IACH,WAAW,IAAI,MAAM,EAAE;IAKvB;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAIlC;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,CAAC,GAC1B,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAchB"}

package/dist/testing/temp-repo.js

@@ -0,0 +1,214 @@
+/**
+ * Temporary git repository builder (fixture harness, G7).
+ *
+ * Creates throwaway git repositories under the OS tmpdir for adversarial
+ * fixtures (GF-01..GF-24). Everything runs offline through `child_process`
+ * git: no network, no wall-clock-dependent output, no reliance on the
+ * developer's git configuration. Author/committer identity and both dates
+ * are pinned to fixed values, so identical file-tree specs produce
+ * byte-identical commit SHAs across machines — fixtures may assert on SHAs.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * The fixed timestamp (git raw-date form) stamped onto every commit as
+ * both author and committer date. Determinism cornerstone: change it and
+ * every fixture SHA changes.
+ */
+export const FIXED_GIT_DATE = '2026-01-01T00:00:00+0000';
+/** Fixed author/committer identity for fixture commits. */
+const FIXED_IDENTITY = {
+    GIT_AUTHOR_NAME: 'gateforge fixtures',
+    GIT_AUTHOR_EMAIL: 'fixtures@gateforge.invalid',
+    GIT_COMMITTER_NAME: 'gateforge fixtures',
+    GIT_COMMITTER_EMAIL: 'fixtures@gateforge.invalid',
+};
+/** Flags stripping every source of nondeterminism from the git invocation. */
+const FIXED_FLAGS = [
+    '-c', 'commit.gpgsign=false',
+    '-c', 'core.autocrlf=false',
+    '-c', 'gc.auto=0',
+];
+/**
+ * A disposable git repository under the OS tmpdir.
+ *
+ * Args:
+ *   options: optional initial file tree, branch name, and tmpdir prefix.
+ *
+ * Returns:
+ *   TempRepo: use `writeFiles`/`stage`/`commit` to build history,
+ *   `cleanup` (or {@link withTempRepo}) to remove it.
+ */
+export class TempRepo {
+    /** Absolute filesystem path of the repository root. */
+    root;
+    gitEnv;
+    constructor(options = {}) {
+        this.root = mkdtempSync(join(tmpdir(), options.prefix ?? 'gateforge-fixture-'));
+        // GIT_CONFIG_GLOBAL=/dev/null + GIT_CONFIG_NOSYSTEM=1 insulate fixtures
+        // from user/system git config (hooks, signing, identity defaults).
+        this.gitEnv = {
+            ...process.env,
+            ...FIXED_IDENTITY,
+            GIT_AUTHOR_DATE: FIXED_GIT_DATE,
+            GIT_COMMITTER_DATE: FIXED_GIT_DATE,
+            GIT_CONFIG_GLOBAL: '/dev/null',
+            GIT_CONFIG_NOSYSTEM: '1',
+        };
+        this.git(['init', '--initial-branch', options.branch ?? 'main', '--quiet']);
+        if (options.files !== undefined)
+            this.writeFiles(options.files);
+    }
+    /**
+     * Runs one git command in the repository.
+     *
+     * Args:
+     *   args: argument vector (without the `git` binary).
+     *   allowFailure: when true a non-zero exit does not throw.
+     *
+     * Returns:
+     *   GitResult: exit status plus captured stdout/stderr.
+     * @throws Error naming the failing command when `allowFailure` is false.
+     */
+    git(args, { allowFailure = false } = {}) {
+        const result = spawnSync('git', [...FIXED_FLAGS, ...args], {
+            cwd: this.root,
+            env: this.gitEnv,
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        if (!allowFailure && result.status !== 0) {
+            throw new Error(`git ${args.join(' ')} failed (exit ${result.status}) in ${this.root}\n` +
+                `stdout: ${result.stdout}\nstderr: ${result.stderr}`);
+        }
+        return {
+            status: result.status ?? -1,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        };
+    }
+    /**
+     * Writes a file-tree spec into the repository. Keys are
+     * repo-root-relative posix paths; parent directories are created.
+     *
+     * Args:
+     *   files: mapping of relative posix path to UTF-8 file content.
+     * @throws Error on absolute paths or `..` segments (spec writers must
+     *   stay inside the repo).
+     */
+    writeFiles(files) {
+        for (const [rawKey, content] of Object.entries(files)) {
+            const key = rawKey.split('\\').join('/');
+            if (key.startsWith('/') || key.split('/').includes('..')) {
+                throw new Error(`file-tree spec key escapes the repo root: '${rawKey}'`);
+            }
+            const absolute = join(this.root, ...key.split('/'));
+            mkdirSync(dirname(absolute), { recursive: true });
+            writeFileSync(absolute, content, 'utf8');
+        }
+    }
+    /**
+     * Stages files. With no argument stages every change (`git add -A`).
+     *
+     * Args:
+     *   paths: repo-root-relative paths to stage.
+     */
+    stage(paths) {
+        this.git(['add', ...(paths ?? ['-A'])]);
+    }
+    /**
+     * Commits the staged tree with a fixed identity and date.
+     *
+     * Args:
+     *   message: commit message.
+     * Returns:
+     *   string: the resulting HEAD sha (40-char hex).
+     */
+    commit(message) {
+        this.git(['commit', '--no-gpg-sign', '--allow-empty', '--quiet', '-m', message]);
+        const sha = this.headSha();
+        if (sha === null)
+            throw new Error('commit succeeded but HEAD is unborn');
+        return sha;
+    }
+    /**
+     * Writes files, stages everything, and commits — the common fixture beat.
+     *
+     * Args:
+     *   files: file-tree spec to write before staging.
+     *   message: commit message.
+     * Returns:
+     *   string: the resulting HEAD sha.
+     */
+    commitFiles(files, message) {
+        this.writeFiles(files);
+        this.stage();
+        return this.commit(message);
+    }
+    /**
+     * Reads the current HEAD sha.
+     *
+     * Returns:
+     *   string | null: 40-char hex sha, or null while the branch is unborn.
+     */
+    headSha() {
+        const result = this.git(['rev-parse', 'HEAD'], { allowFailure: true });
+        return result.status === 0 ? result.stdout.trim() : null;
+    }
+    /**
+     * Lists currently staged (index vs HEAD) files — what the real
+     * `local-staged` changed-file provider would report (pin #5).
+     *
+     * Returns:
+     *   string[]: repo-root-relative posix paths (possibly empty).
+     */
+    stagedFiles() {
+        const result = this.git(['diff', '--cached', '--name-only']);
+        return result.stdout.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+    }
+    /**
+     * Resolves a repo-root-relative posix path to an absolute path.
+     *
+     * Args:
+     *   relativePath: posix path relative to the repository root.
+     */
+    path(relativePath) {
+        return join(this.root, ...relativePath.split('/'));
+    }
+    /**
+     * Removes the repository. Idempotent; safe to call more than once.
+     */
+    cleanup() {
+        rmSync(this.root, { recursive: true, force: true });
+    }
+}
+/**
+ * Runs a fixture body against a fresh {@link TempRepo}, cleaning up on
+ * every path (sync throw, async rejection, success).
+ *
+ * Args:
+ *   options: TempRepo construction options.
+ *   body: receives the repo; may be async.
+ *
+ * Returns:
+ *   The body's return value (awaited when async).
+ */
+export function withTempRepo(options, body) {
+    const repo = new TempRepo(options);
+    let result;
+    try {
+        result = body(repo);
+    }
+    catch (error) {
+        repo.cleanup();
+        throw error;
+    }
+    if (result instanceof Promise) {
+        return result.finally(() => repo.cleanup());
+    }
+    repo.cleanup();
+    return result;
+}
+//# sourceMappingURL=temp-repo.js.map

package/dist/testing/temp-repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-repo.js","sourceRoot":"","sources":["../../src/testing/temp-repo.ts"],"names":[],"mappings":"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"}