apify-test-tools 0.10.1-beta.2 → 0.10.1-beta.4

package/test/unit/bin/utils/config/load-config.test.ts

@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { CONFIG_FILE_NAME, loadActorConfig, readConfigFile } from '../../../../../bin/utils/config/load-config.js';
 import type { ResolvedActorConfig } from '../../../../../bin/utils/config/structures/base.js';
+import { ExistingDir, ExistingFile, RelativeDir, RelativeFile } from '../../../../../bin/utils/path/repo-relative.js';
 
 let repoDir: string;
 let originalCwd: string;
@@ -15,6 +16,7 @@ beforeEach(async () => {
     // `realpath` because macOS hands out a symlinked temp dir, while `process.cwd()` reports the target.
     repoDir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'apify-test-tools-config-')));
     process.chdir(repoDir);
+    await fs.mkdir('actors/shopify', { recursive: true });
 });
 
 afterEach(async () => {
@@ -37,12 +39,11 @@ const writeFiles = async (files: Record<string, string>) =>
     );
 
 describe('loadActorConfig', () => {
-    const entry = (fields: Partial<ResolvedActorConfig> = {}): ResolvedActorConfig => ({
-        folder: 'actors/shopify',
-        actorFullName: 'myteam/shopify',
-        tokenEnvVar: 'APIFY_TOKEN',
-        overrideActorContext: undefined,
-        ...fields,
+    const entry = (fields: Partial<ResolvedActorConfig> = {}) => ({
+        folder: new ExistingDir(fields.folder ?? 'actors/shopify'),
+        actorFullName: fields.actorFullName ?? 'myteam/shopify',
+        tokenEnvVar: fields.tokenEnvVar ?? 'APIFY_TOKEN',
+        overrideActorContext: fields.overrideActorContext?.map((contextPath) => new RelativeDir(contextPath)),
     });
 
     const writeActorJson = async (fields: Record<string, unknown> = {}) =>
@@ -51,31 +52,64 @@ describe('loadActorConfig', () => {
     it('resolves data coming from actor.json', async () => {
         await writeActorJson({ dockerContextDir: '..' });
 
-        expect(loadActorConfig(entry())).toEqual({
-            actorFullName: 'myteam/shopify',
-            folder: 'actors/shopify',
-            tokenEnvVar: 'APIFY_TOKEN',
-            dockerContextDir: 'actors/shopify',
-            contextPaths: ['actors/shopify'],
-        });
+        const loaded = loadActorConfig(entry());
+        expect(loaded.actorFullName).toBe('myteam/shopify');
+        expect(loaded.folder).toBeInstanceOf(ExistingDir);
+        expect(loaded.folder.path).toBe('actors/shopify');
+        expect(loaded.actorJson.file).toBeInstanceOf(ExistingFile);
+        expect(loaded.actorJson.file.path).toBe('actors/shopify/.actor/actor.json');
+        expect(loaded.dockerContextDir).toBeInstanceOf(RelativeDir);
+        expect(loaded.dockerContextDir.path).toBe('actors/shopify');
+        expect(loaded.contextPaths.map((contextPath) => contextPath.path)).toEqual(['actors/shopify']);
     });
 
     it('defaults dockerContextDir to the actor folder when actor.json does not set it', async () => {
         await writeActorJson();
 
-        expect(loadActorConfig(entry()).dockerContextDir).toBe('actors/shopify');
+        expect(loadActorConfig(entry()).dockerContextDir.path).toBe('actors/shopify');
+    });
+
+    it('resolves path fields from actor.json while allowing inline schemas', async () => {
+        await writeActorJson({
+            readme: '../README.md',
+            changelog: '../../CHANGELOG.md',
+            dockerfile: '../Dockerfile',
+            input: '../INPUT_SCHEMA.json',
+            output: { type: 'object' },
+            webServerSchema: './openapi.json',
+        });
+
+        const { actorJson: actorJsonPaths } = loadActorConfig(entry());
+        expect(actorJsonPaths.readme).toBeInstanceOf(RelativeFile);
+        expect(actorJsonPaths.readme?.path).toBe('actors/shopify/README.md');
+        expect(actorJsonPaths.changelog?.path).toBe('actors/CHANGELOG.md');
+        expect(actorJsonPaths.dockerfile?.path).toBe('actors/shopify/Dockerfile');
+        expect(actorJsonPaths.inputSchema?.path).toBe('actors/shopify/INPUT_SCHEMA.json');
+        expect(actorJsonPaths.outputSchema).toBeUndefined();
+        expect(actorJsonPaths.webServerSchema?.path).toBe('actors/shopify/.actor/openapi.json');
+    });
+
+    it('rejects malformed actor.json path fields', async () => {
+        await writeActorJson({ dockerContextDir: 123 });
+        expect(() => loadActorConfig(entry())).toThrow(/dockerContextDir/);
+
+        await writeActorJson({ readme: '/outside.md' });
+        expect(() => loadActorConfig(entry())).toThrow(/Invalid "readme"/);
+
+        await writeActorJson({ inputSchema: '/outside.json' });
+        expect(() => loadActorConfig(entry())).toThrow(/Invalid "inputSchema"/);
     });
 
     it('resolves dockerContextDir relative to the .actor/ folder, not the actor folder', async () => {
         await writeActorJson({ dockerContextDir: '../../..' });
 
-        expect(loadActorConfig(entry()).dockerContextDir).toBe('');
+        expect(loadActorConfig(entry()).dockerContextDir.path).toBe('.');
     });
 
     it('throws when dockerContextDir resolves outside the repository root', async () => {
         await writeActorJson({ dockerContextDir: '../../../..' });
 
-        expect(() => loadActorConfig(entry())).toThrow(/resolves outside the repository root/);
+        expect(() => loadActorConfig(entry())).toThrow(/escapes the repo root/);
     });
 
     it('throws when actor.json is missing', () => {
@@ -85,27 +119,30 @@ describe('loadActorConfig', () => {
     it('resolves contextPaths from overrideActorContext', async () => {
         await writeActorJson({ dockerContextDir: '../../..' });
 
-        expect(loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'packages'] })).contextPaths).toEqual([
-            'actors/shopify',
-            'packages',
-        ]);
+        expect(
+            loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'packages'] })).contextPaths.map(
+                (contextPath) => contextPath.path,
+            ),
+        ).toEqual(['actors/shopify', 'packages']);
     });
 
     it('adds the actor own folder automatically when overrideActorContext does not cover it', async () => {
         await writeActorJson();
 
-        expect(loadActorConfig(entry({ overrideActorContext: ['code', 'shared'] })).contextPaths).toEqual([
-            'code',
-            'shared',
-            'actors/shopify',
-        ]);
+        expect(
+            loadActorConfig(entry({ overrideActorContext: ['code', 'shared'] })).contextPaths.map(
+                (contextPath) => contextPath.path,
+            ),
+        ).toEqual(['code', 'shared', 'actors/shopify']);
     });
 
     it('allows overrideActorContext with disjoint sibling paths that all reach the actor folder via one entry', async () => {
         await writeActorJson();
 
         expect(
-            loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'code', 'shared'] })).contextPaths,
+            loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'code', 'shared'] })).contextPaths.map(
+                (contextPath) => contextPath.path,
+            ),
         ).toEqual(['actors/shopify', 'code', 'shared']);
     });
 

package/test/unit/bin/utils/config/parser.test.ts

@@ -1,12 +1,43 @@
-import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 import { _privates, parseConfigFile } from '../../../../../bin/utils/config/parser.js';
 import { CONFIG_FILE_STRATEGY } from '../../../../../bin/utils/config/structures/base.js';
 import { GROUPED_PARSER } from '../../../../../bin/utils/config/structures/grouped.js';
 import { LEGACY_PARSER } from '../../../../../bin/utils/config/structures/legacy.js';
+import { ExistingDir, RelativeDir } from '../../../../../bin/utils/path/repo-relative.js';
 
 const { selectStrategy, verifyConfiguration } = _privates;
 
+let repoDir: string;
+const originalCwd = process.cwd();
+
+beforeAll(async () => {
+    repoDir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'apify-test-tools-parser-')));
+    for (const folder of [
+        'actors/shopify',
+        'actors/a',
+        'actors/b',
+        'actors/c',
+        'actors/d',
+        'bin',
+        'test',
+        'collide/collide',
+    ]) {
+        await fs.mkdir(path.join(repoDir, folder), { recursive: true });
+    }
+    await fs.writeFile(path.join(repoDir, 'package.json'), '{}');
+    process.chdir(repoDir);
+});
+
+afterAll(async () => {
+    process.chdir(originalCwd);
+    await fs.rm(repoDir, { recursive: true, force: true });
+});
+
 const actor = (fields: Record<string, unknown> = {}) => ({
     folder: 'actors/shopify',
     actorFullName: 'myteam/shopify',
@@ -33,7 +64,7 @@ describe('selectStrategy', () => {
 });
 
 describe('verifyConfiguration', () => {
-    it('resolves the repo root to "" and gets rid of trailing slashes', () => {
+    it('resolves the repo root and gets rid of trailing slashes', () => {
         const result = verifyConfiguration([
             { folder: '.', actorFullName: 'myteam/root', tokenEnvVar: 'APIFY_TOKEN', overrideActorContext: undefined },
             {
@@ -44,15 +75,11 @@ describe('verifyConfiguration', () => {
             },
         ]);
 
-        expect(result).toEqual([
-            { folder: '', actorFullName: 'myteam/root', tokenEnvVar: 'APIFY_TOKEN', overrideActorContext: undefined },
-            {
-                folder: 'actors/shopify',
-                actorFullName: 'myteam/shopify',
-                tokenEnvVar: 'APIFY_TOKEN',
-                overrideActorContext: ['packages'],
-            },
-        ]);
+        expect(result[0].folder).toBeInstanceOf(ExistingDir);
+        expect(result[0].folder.path).toBe('.');
+        expect(result[1].folder.path).toBe('actors/shopify');
+        expect(result[1].overrideActorContext?.[0]).toBeInstanceOf(RelativeDir);
+        expect(result[1].overrideActorContext?.[0].path).toBe('packages');
     });
 
     it.each([
@@ -123,26 +150,42 @@ describe('verifyConfiguration', () => {
 });
 
 describe('parseConfigFile', () => {
-    it('validates and normalizes a plain object without touching the filesystem', () => {
-        expect(parseConfigFile({ actors: [actor({ folder: 'actors/shopify/' })] })).toEqual([
-            actor({ folder: 'actors/shopify', overrideActorContext: undefined }),
-        ]);
+    it('validates and normalizes paths after resolving the config', () => {
+        const [parsed] = parseConfigFile({ actors: [actor({ folder: './bin/', overrideActorContext: ['test/'] })] });
+        expect(parsed.folder).toBeInstanceOf(ExistingDir);
+        expect(parsed.folder.path).toBe('bin');
+        expect(parsed.overrideActorContext?.[0]).toBeInstanceOf(RelativeDir);
+        expect(parsed.overrideActorContext?.[0].path).toBe('test');
+    });
+
+    it('accepts the repo root as an existing directory', () => {
+        expect(parseConfigFile({ actors: [actor({ folder: '' })] })[0].folder.path).toBe('.');
+    });
+
+    it('reports invalid paths at their config fields', () => {
+        expect(() => parseConfigFile({ actors: [actor({ folder: 'missing-actor-dir' })] })).toThrow(/\[0\]\.folder/);
+        expect(() => parseConfigFile({ actors: [actor({ folder: 'package.json' })] })).toThrow(/to be a directory/);
+        expect(() =>
+            parseConfigFile({ actors: [actor({ folder: 'bin', overrideActorContext: ['../outside'] })] }),
+        ).toThrow(/\[0\]\.overrideActorContext\[0\]/);
     });
 
     it('parses a grouped config file, which needs mode to be stripped', () => {
-        expect(
-            parseConfigFile({
-                mode: CONFIG_FILE_STRATEGY.GROUPED,
-                groups: {
-                    myteam: {
-                        actors: [{ folder: 'actors/shopify/', actorFullName: 'myteam/shopify' }],
-                        tokenEnvVar: 'APIFY_TOKEN',
-                    },
+        const parsed = parseConfigFile({
+            mode: CONFIG_FILE_STRATEGY.GROUPED,
+            groups: {
+                myteam: {
+                    actors: [{ folder: 'actors/shopify/', actorFullName: 'myteam/shopify' }],
+                    tokenEnvVar: 'APIFY_TOKEN',
                 },
-            }),
-        ).toEqual([
-            actor({ folder: 'actors/shopify', actorFullName: 'myteam/shopify', overrideActorContext: undefined }),
-        ]);
+            },
+        });
+        expect(parsed).toHaveLength(1);
+        expect(parsed[0].folder).toBeInstanceOf(ExistingDir);
+        expect(parsed[0].folder.path).toBe('actors/shopify');
+        expect(parsed[0].actorFullName).toBe('myteam/shopify');
+        expect(parsed[0].tokenEnvVar).toBe('APIFY_TOKEN');
+        expect(parsed[0].overrideActorContext).toBeUndefined();
     });
 
     it('surfaces cross-entry violations from verifyConfiguration', () => {
@@ -155,4 +198,15 @@ describe('parseConfigFile', () => {
             }),
         ).toThrow(/Duplicate folder/);
     });
+
+    it('rejects folders that collide after resolving dot segments', () => {
+        expect(() =>
+            parseConfigFile({
+                actors: [
+                    actor({ actorFullName: 'myteam/actor-a', folder: 'bin/../test' }),
+                    actor({ actorFullName: 'myteam/actor-b', folder: 'test' }),
+                ],
+            }),
+        ).toThrow('Duplicate folder "test"');
+    });
 });

package/test/unit/bin/utils/files.test.ts

@@ -1,17 +1,25 @@
 import fs from 'node:fs/promises';
-import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { safeReadJsonObjectFile } from '../../../../bin/utils/json-file.js';
+import { ExistingFile } from '../../../../bin/utils/path/repo-relative.js';
 
-// These tests read real fixture files rather than mocking `node:fs`: the whole point of
-// `safeReadJsonObjectFile` is how it reacts to real stat/readFile outcomes (missing path, directory,
-// symlink, unreadable file), so mocking those away would only assert the mock back to itself.
+// These tests read real fixture files rather than mocking `node:fs`. Existence and file-kind checks
+// happen when constructing ExistingFile; this reader tests JSON parsing and read failures after that.
 const FIXTURE_DIR = fileURLToPath(new URL('../../../fixtures/bin/utils/files/', import.meta.url));
 
-const fixture = (name: string) => path.join(FIXTURE_DIR, name);
+let originalCwd: string;
+
+beforeEach(() => {
+    originalCwd = process.cwd();
+    process.chdir(FIXTURE_DIR);
+});
+
+afterEach(() => process.chdir(originalCwd));
+
+const fixture = (name: string): ExistingFile => new ExistingFile(name);
 
 const NESTED_FIXTURE = {
     storages: { datasets: { default: { title: 'Default' } } },
@@ -42,29 +50,6 @@ describe('safeReadJsonObjectFile', () => {
     });
 
     describe('filesystem-level handling', () => {
-        it('fails when the path does not exist', () => {
-            const filePath = fixture('does-not-exist.json');
-
-            const result = safeReadJsonObjectFile(filePath);
-
-            expect(result).toMatchObject({
-                success: false,
-                reason: 'unreadable',
-            });
-        });
-
-        // The fixture is named `directory.json` on purpose — the check is `stat().isFile()`, not the extension.
-        it('fails when the path is a directory', () => {
-            const filePath = fixture('directory.json');
-
-            const result = safeReadJsonObjectFile(filePath);
-
-            expect(result).toMatchObject({
-                success: false,
-                reason: 'not-a-file',
-            });
-        });
-
         // Regression guard: `lstat` would report the link itself as "not a file" and reject it, even
         // though `readFile` follows symlinks and would have read the target without complaint.
         it('follows a symlink to its target file', () => {
@@ -76,14 +61,15 @@ describe('safeReadJsonObjectFile', () => {
         // Git only tracks the executable bit, so this is the one case whose fixture cannot carry its own
         // mode — `unreadable.json` is committed readable and stripped of permissions just for this test.
         describe('unreadable file', () => {
-            const filePath = fixture('unreadable.json');
+            const filePath = 'unreadable.json';
 
             afterEach(async () => fs.chmod(filePath, 0o644));
 
             it.runIf(process.getuid?.() !== 0)('fails when the file exists but cannot be read', async () => {
+                const file = fixture(filePath);
                 await fs.chmod(filePath, 0o000);
 
-                const result = safeReadJsonObjectFile(filePath);
+                const result = safeReadJsonObjectFile(file);
 
                 expect(result).toMatchObject({
                     success: false,
@@ -135,7 +121,7 @@ describe('safeReadJsonObjectFile', () => {
             const result = safeReadJsonObjectFile(filePath);
 
             expect(result).toMatchObject({ success: false, reason: 'invalid-json' });
-            expect((result as { failure: Error }).failure.message).toContain(`Failed to parse ${filePath}`);
+            expect((result as { failure: Error }).failure.message).toContain(`Failed to parse ${filePath.path}`);
         });
 
         it('fails on an empty file', () => {
@@ -144,7 +130,7 @@ describe('safeReadJsonObjectFile', () => {
             const result = safeReadJsonObjectFile(filePath);
 
             expect(result).toMatchObject({ success: false, reason: 'invalid-json' });
-            expect((result as { failure: Error }).failure.message).toContain(`Failed to parse ${filePath}`);
+            expect((result as { failure: Error }).failure.message).toContain(`Failed to parse ${filePath.path}`);
         });
 
         it.fails('reads jsonc', () => {

package/test/unit/bin/utils/path/repo-relative.test.ts

@@ -0,0 +1,250 @@
+import path from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+    ExistingDir,
+    ExistingFile,
+    RelativeDir,
+    type RelativeFile,
+} from '../../../../../bin/utils/path/repo-relative.js';
+
+// Paths from the config file and from git all enter through the root.
+const { ROOT } = RelativeDir;
+const dir = (raw: string): RelativeDir => ROOT.joinDir(raw);
+const file = (raw: string): RelativeFile => ROOT.joinFile(raw);
+
+describe('ExistingDir', () => {
+    it('validates directories through both construction paths', () => {
+        expect(ExistingDir.initialize(dir('bin')).path).toBe('bin');
+        expect(new ExistingDir('./bin/').path).toBe('bin');
+        expect(new ExistingDir('.').path).toBe('.');
+        expect(() => ExistingDir.initialize(dir('missing-dir'))).toThrow('to exist');
+        expect(() => new ExistingDir('package.json')).toThrow('to be a directory');
+    });
+
+    it('preserves directory equality after existence validation', () => {
+        const relative = dir('./bin');
+        const existing = ExistingDir.initialize(relative);
+
+        expect(relative.isEqualTo(existing)).toBe(true);
+        expect(existing.isEqualTo(relative)).toBe(true);
+        expect(existing.isEqualTo(file('bin'))).toBe(false);
+    });
+});
+
+describe('ExistingFile', () => {
+    it('validates files through initialize', () => {
+        expect(ExistingFile.initialize(file('package.json')).path).toBe('package.json');
+        expect(() => ExistingFile.initialize(file('package.json/missing'))).toThrow();
+        expect(() => ExistingFile.initialize(file('bin'))).toThrow('to be a file');
+        expect(() => new ExistingFile('missing.txt')).toThrow('to exist');
+    });
+
+    it('preserves file equality after existence validation', () => {
+        const relative = file('./package.json');
+        const existing = ExistingFile.initialize(relative);
+
+        expect(relative.isEqualTo(existing)).toBe(true);
+        expect(existing.isEqualTo(relative)).toBe(true);
+        expect(existing.isEqualTo(ExistingFile.initialize(file('package.json')))).toBe(true);
+        expect(existing.isEqualTo(file('other.json'))).toBe(false);
+        expect(existing.isEqualTo(dir('package.json'))).toBe(false);
+        expect(dir('package.json').isEqualTo(existing)).toBe(false);
+    });
+});
+
+describe('RelativeDir', () => {
+    describe('ROOT', () => {
+        it('is a RelativeDir spelled "."', () => {
+            expect(ROOT).toBeInstanceOf(RelativeDir);
+            expect(ROOT.toString()).toBe('.');
+        });
+
+        it.each(['', '.', './', './/', 'a/..'])('is what %j parses to', (raw) => {
+            expect(dir(raw).isEqualTo(ROOT)).toBe(true);
+            expect(dir(raw).toString()).toBe('.');
+        });
+    });
+
+    describe('parsing (ROOT.joinDir)', () => {
+        it.each(['actors/foo', './actors/foo', 'actors/foo/', 'actors//foo', './actors/./foo//', 'actors/bar/../foo'])(
+            'normalizes %j to actors/foo',
+            (raw) => {
+                expect(dir(raw).toString()).toBe('actors/foo');
+            },
+        );
+
+        it.each(['..', '../x', 'actors/../../x', './..'])('rejects %j because it escapes the repo root', (raw) => {
+            expect(() => dir(raw)).toThrow('escapes the repo root');
+        });
+
+        it('rejects absolute paths', () => {
+            expect(() => file('/etc/passwd')).toThrow('got absolute path "/etc/passwd"');
+        });
+
+        it('rejects absolute paths even when they point inside the working directory', () => {
+            expect(() => dir(path.join(process.cwd(), 'actors/foo'))).toThrow('got absolute path');
+        });
+
+        it('reports the path as written, not its normalized form', () => {
+            expect(() => dir('a/../../x')).toThrow();
+        });
+
+        it('keeps a directory named "..foo", which does not escape the repo root', () => {
+            expect(dir('..foo/bar').toString()).toBe('..foo/bar');
+        });
+
+        it('keeps case, since git paths are case-sensitive', () => {
+            expect(dir('Actors/Foo').isEqualTo(dir('actors/foo'))).toBe(false);
+        });
+    });
+
+    describe('joinDir / joinFile', () => {
+        const actorDir = dir('actors/foo');
+        const actorDotDir = dir('actors/foo/.actor');
+
+        it('resolves relative to the path it is called on', () => {
+            expect(actorDir.joinDir('src').toString()).toBe('actors/foo/src');
+            expect(actorDir.joinFile('src/main.ts').toString()).toBe('actors/foo/src/main.ts');
+        });
+
+        it('resolves a dockerContextDir the way actor.json means it', () => {
+            expect(actorDotDir.joinDir('..').toString()).toBe('actors/foo');
+            expect(actorDotDir.joinDir('../..').toString()).toBe('actors');
+            expect(actorDotDir.joinDir('../../..').isEqualTo(ROOT)).toBe(true);
+            expect(actorDotDir.joinFile('./Dockerfile').toString()).toBe('actors/foo/.actor/Dockerfile');
+        });
+
+        it('can climb out of the path it is called on, as long as it stays within the repo root', () => {
+            expect(actorDir.joinDir('../bar').toString()).toBe('actors/bar');
+        });
+
+        it.each(['', '.', '..', 'src/', 'src/.', 'src/..'])('rejects %j as a file path', (raw) => {
+            expect(() => actorDir.joinFile(raw)).toThrow('Expected a file path');
+            expect(() => file(`actors/foo/${raw}`)).toThrow('Expected a file path');
+        });
+
+        it('rejects a file path through a file, too', () => {
+            expect(() => file('actors/foo/main.ts').joinFile('.')).toThrow('Expected a file path');
+        });
+
+        it('rejects results that escape the repo root', () => {
+            expect(() => actorDotDir.joinDir('../../../..')).toThrow('escapes the repo root');
+        });
+
+        it('does not depend on the process working directory', () => {
+            const originalCwd = process.cwd();
+            try {
+                process.chdir(path.join(originalCwd, 'bin'));
+                expect(dir('actors/foo').toString()).toBe('actors/foo');
+                expect(actorDir.joinDir('src').toString()).toBe('actors/foo/src');
+            } finally {
+                process.chdir(originalCwd);
+            }
+        });
+    });
+
+    describe('isEqualTo', () => {
+        it('matches different spellings of the same path', () => {
+            expect(dir('./actors/foo/').isEqualTo(dir('actors/foo'))).toBe(true);
+        });
+
+        it('does not match different paths', () => {
+            expect(dir('actors/foo').isEqualTo(dir('actors/foobar'))).toBe(false);
+        });
+
+        it('does not match a file and a directory spelled the same', () => {
+            expect(dir('actors/foo').isEqualTo(file('actors/foo'))).toBe(false);
+            expect(file('actors/foo').isEqualTo(dir('actors/foo'))).toBe(false);
+        });
+    });
+
+    describe('isStrictAncestorOf', () => {
+        const foo = dir('actors/foo');
+
+        it('is true for paths inside it', () => {
+            expect(foo.isStrictAncestorOf(file('actors/foo/src/main.ts'))).toBe(true);
+        });
+
+        it('is false for itself', () => {
+            expect(foo.isStrictAncestorOf(foo)).toBe(false);
+        });
+
+        it('is false for a sibling that shares a name prefix', () => {
+            expect(foo.isStrictAncestorOf(dir('actors/foobar'))).toBe(false);
+        });
+
+        it('makes the root an ancestor of every other path', () => {
+            expect(ROOT.isStrictAncestorOf(foo)).toBe(true);
+            expect(ROOT.isStrictAncestorOf(file('README.md'))).toBe(true);
+            expect(ROOT.isStrictAncestorOf(ROOT)).toBe(false);
+        });
+    });
+
+    describe('contains', () => {
+        const foo = dir('actors/foo');
+
+        it('matches itself and paths inside it', () => {
+            expect(foo.contains(foo)).toBe(true);
+            expect(foo.contains(file('actors/foo/src/main.ts'))).toBe(true);
+        });
+
+        it('does not match a sibling that shares a name prefix', () => {
+            expect(foo.contains(file('actors/foobar/main.ts'))).toBe(false);
+        });
+
+        it('makes the root contain every path', () => {
+            expect(ROOT.contains(foo)).toBe(true);
+            expect(ROOT.contains(file('README.md'))).toBe(true);
+            expect(ROOT.contains(ROOT)).toBe(true);
+        });
+
+        it('does not contain a file spelled the same as itself', () => {
+            expect(foo.contains(file('actors/foo'))).toBe(false);
+            expect(foo.isStrictAncestorOf(file('actors/foo'))).toBe(false);
+        });
+
+        it('does not make a subfolder contain the root', () => {
+            expect(foo.contains(ROOT)).toBe(false);
+        });
+    });
+
+    describe('string output', () => {
+        it('renders as the path in templates', () => {
+            expect(`${dir('actors/foo')}/x`).toBe('actors/foo/x');
+        });
+
+        it('renders as a plain string in JSON', () => {
+            expect(JSON.stringify({ folder: dir('actors/foo'), root: ROOT })).toBe(
+                '{"folder":"actors/foo","root":"."}',
+            );
+        });
+    });
+
+    // Git and the config file always use "/", so paths must not change spelling with the host OS.
+    describe('on Windows', () => {
+        afterEach(() => {
+            vi.doUnmock('node:path');
+            vi.resetModules();
+        });
+
+        const importWithWin32Path = async (): Promise<typeof RelativeDir> => {
+            vi.resetModules();
+            vi.doMock('node:path', () => ({ default: path.win32, ...path.win32 }));
+            const module = await import('../../../../../bin/utils/path/repo-relative.js');
+            return module.RelativeDir;
+        };
+
+        it('keeps forward slashes', async () => {
+            const WinRelativeDir = await importWithWin32Path();
+            expect(WinRelativeDir.ROOT.joinDir('actors/foo').toString()).toBe('actors/foo');
+        });
+
+        it('matches paths inside a scope', async () => {
+            const WinRelativeDir = await importWithWin32Path();
+            const foo = WinRelativeDir.ROOT.joinDir('actors/foo');
+            expect(foo.contains(WinRelativeDir.ROOT.joinFile('actors/foo/src/main.ts'))).toBe(true);
+        });
+    });
+});