Problem
The "Public docs integration tests — slug-collision precedence:" describe block added by #4011 fails deterministically (3/3 assertions, confirmed not a flake) in any downstream consumer that ships its own guides at the framework sample slugs from a second, non-core module.
● the application guide wins the "welcome" slug in the listing (no duplicate)
Expected: "App Welcome" Received: "Welcome"
● the application guide wins the "welcome" slug on fetch — listing and fetch agree
Expected substring: "Application-level welcome guide." Received: the consumer's real welcome.md body
● the application guide overrides the framework guide for "quickstart" ...
Root cause
The beforeAll builds its fixture input as config.files.guides = [...originalGuides, appGuidePath, reverseGuideRelPath] — it EXTENDS the real, on-disk config.files.guides rather than fully replacing it. This implicitly assumes at most one real pre-existing guide per slug (the framework's modules/home/doc/guides/).
A consumer shipping a second real guide set at the same slugs (welcome, quickstart) from its own module — modules/<app-module>/doc/guides/00-welcome.md — gets that module classified application by precedenceTier() (not in CORE_MODULES), the SAME tier as the test's injected fixture.
Resulting 3-way collision per resolveGuideEntries:
tmpDir/.../app-fixture/.../00-welcome.md (absolute path, sorts first) — tier application — incumbent.modules/home/doc/guides/00-welcome.md — tier framework — challenger, incumbent already wins, no change.modules/<app-module>/doc/guides/00-welcome.md (the consumer's real guide, sorts after the fixture) — tier application, SAME tier as the incumbent → same-tier tiebreak fires ("later entry wins") → the consumer's real guide overwrites the fixture.
Real production behavior is unaffected and correct (framework vs app module: a genuine 2-tier collision resolving to the app module winning, as intended). Only the test's own fixture is defeated by the consumer's real content.
Affected file(s)
modules/public/tests/public.docs.integration.tests.js (describe block "Public docs integration tests — slug-collision precedence:", beforeAll fixture setup ~line 130-165)modules/public/helpers/public.docs.tree.js (resolveGuideEntries — same-tier tiebreak by scan order, working as designed; not itself the bug)
Steps to reproduce
In a consumer project that ships guides in a second, non-core module at the same slugs as the framework's samples, run:
npm run test:integration -- --testPathPatterns='public.docs.integration'
Suggested fix
The precedence-collision describe block should fully control its own input (config.files.guides = [appGuidePath, reverseGuideRelPath], no ...originalGuides spread) so the fixture scenario is deterministic regardless of what a consumer's real on-disk guides look like.
Problem
The "Public docs integration tests — slug-collision precedence:" describe block added by #4011 fails deterministically (3/3 assertions, confirmed not a flake) in any downstream consumer that ships its own guides at the framework sample slugs from a second, non-core module.
Root cause
The
beforeAllbuilds its fixture input asconfig.files.guides = [...originalGuides, appGuidePath, reverseGuideRelPath]— it EXTENDS the real, on-diskconfig.files.guidesrather than fully replacing it. This implicitly assumes at most one real pre-existing guide per slug (the framework'smodules/home/doc/guides/).A consumer shipping a second real guide set at the same slugs (
welcome,quickstart) from its own module —modules/<app-module>/doc/guides/00-welcome.md— gets that module classifiedapplicationbyprecedenceTier()(not inCORE_MODULES), the SAME tier as the test's injected fixture.Resulting 3-way collision per
resolveGuideEntries:tmpDir/.../app-fixture/.../00-welcome.md(absolute path, sorts first) — tierapplication— incumbent.modules/home/doc/guides/00-welcome.md— tierframework— challenger, incumbent already wins, no change.modules/<app-module>/doc/guides/00-welcome.md(the consumer's real guide, sorts after the fixture) — tierapplication, SAME tier as the incumbent → same-tier tiebreak fires ("later entry wins") → the consumer's real guide overwrites the fixture.Real production behavior is unaffected and correct (framework vs app module: a genuine 2-tier collision resolving to the app module winning, as intended). Only the test's own fixture is defeated by the consumer's real content.
Affected file(s)
modules/public/tests/public.docs.integration.tests.js(describe block "Public docs integration tests — slug-collision precedence:", beforeAll fixture setup ~line 130-165)modules/public/helpers/public.docs.tree.js(resolveGuideEntries— same-tier tiebreak by scan order, working as designed; not itself the bug)Steps to reproduce
In a consumer project that ships guides in a second, non-core module at the same slugs as the framework's samples, run:
Suggested fix
The precedence-collision describe block should fully control its own input (
config.files.guides = [appGuidePath, reverseGuideRelPath], no...originalGuidesspread) so the fixture scenario is deterministic regardless of what a consumer's real on-disk guides look like.