From a4d856c45973cd9be12794980777d59b66ee8d66 Mon Sep 17 00:00:00 2001 From: TabishB Date: Sat, 23 May 2026 15:07:22 +1000 Subject: [PATCH 1/3] docs: document cross-platform path assertions --- .changeset/windows-path-guidance.md | 7 +++++++ test/AGENTS.md | 7 +++++++ 2 files changed, 14 insertions(+) create mode 100644 .changeset/windows-path-guidance.md diff --git a/.changeset/windows-path-guidance.md b/.changeset/windows-path-guidance.md new file mode 100644 index 000000000..b0a99d31f --- /dev/null +++ b/.changeset/windows-path-guidance.md @@ -0,0 +1,7 @@ +--- +"@fission-ai/openspec": patch +--- + +### Documentation + +- Document cross-platform path assertion guidance for tests, especially Windows path separators in CLI output. diff --git a/test/AGENTS.md b/test/AGENTS.md index b608106f0..ff3e1c518 100644 --- a/test/AGENTS.md +++ b/test/AGENTS.md @@ -9,6 +9,13 @@ Applies to tests under `test/`. - Full suite: `pnpm test` - Run `pnpm run build` before focused CLI tests when implementation changes may leave `dist/` stale. +## Cross-Platform Paths + +- Do not hard-code Unix path separators in CLI output expectations unless the implementation intentionally emits POSIX paths. +- For filesystem paths, build expected values with `path.join(...)`, `path.relative(...)`, or `FileSystemUtils.joinPath(...)`. +- For human-readable output, either assert a deliberately normalized display format or normalize both actual and expected strings before comparing. +- When touching path behavior, add coverage that would fail on Windows path separators. + ## Path Canonicalization Path identity is a recurring CI failure mode: Windows short/long paths, symlink or From ef0634c54f7bc90e0be47d52854d4a61b7abfab6 Mon Sep 17 00:00:00 2001 From: Alfred Date: Sat, 23 May 2026 15:47:51 +1000 Subject: [PATCH 2/3] docs: mention toPosixPath in path assertion guidance --- test/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/AGENTS.md b/test/AGENTS.md index ff3e1c518..616158382 100644 --- a/test/AGENTS.md +++ b/test/AGENTS.md @@ -13,7 +13,7 @@ Applies to tests under `test/`. - Do not hard-code Unix path separators in CLI output expectations unless the implementation intentionally emits POSIX paths. - For filesystem paths, build expected values with `path.join(...)`, `path.relative(...)`, or `FileSystemUtils.joinPath(...)`. -- For human-readable output, either assert a deliberately normalized display format or normalize both actual and expected strings before comparing. +- For human-readable output, either assert a deliberately normalized display format or normalize both actual and expected strings before comparing, for example with `FileSystemUtils.toPosixPath()` to convert backslashes to forward slashes for cross-platform consistency. - When touching path behavior, add coverage that would fail on Windows path separators. ## Path Canonicalization From b1f610975a85502759d8f095d59dc47eb9746e40 Mon Sep 17 00:00:00 2001 From: TabishB Date: Mon, 1 Jun 2026 15:02:58 +1000 Subject: [PATCH 3/3] chore: remove changeset --- .changeset/windows-path-guidance.md | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 .changeset/windows-path-guidance.md diff --git a/.changeset/windows-path-guidance.md b/.changeset/windows-path-guidance.md deleted file mode 100644 index b0a99d31f..000000000 --- a/.changeset/windows-path-guidance.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"@fission-ai/openspec": patch ---- - -### Documentation - -- Document cross-platform path assertion guidance for tests, especially Windows path separators in CLI output.