Skip to content

fix: make phantoms cover descendant paths and remove skip cap#3375

Open
theletterf wants to merge 2 commits into
mainfrom
fix/phantom-prefix-matching-and-cap
Open

fix: make phantoms cover descendant paths and remove skip cap#3375
theletterf wants to merge 2 commits into
mainfrom
fix/phantom-prefix-matching-and-cap

Conversation

@theletterf
Copy link
Copy Markdown
Member

Why

Declaring a phantom for a TOC path (e.g. elasticsearch://reference/ingest-processor) is the intended way to unblock a content-repo PR that adds a new TOC before it's wired into navigation.yml. But two bugs made this fail in practice:

  1. Exact-match instead of prefix match. The checker computed the direct parent directory of each file and compared it to the phantom set with ==. A file at ingest-processor/subdir/file.md produced pathUri = elasticsearch://reference/ingest-processor/subdir, which does not equal the declared phantom elasticsearch://reference/ingest-processor. Only files exactly one level deep in the phantom namespace were ever skipped; anything nested deeper generated errors.

  2. Hard cap of _phantoms.Count * 3 triggered errors on real TOC trees. With the current six phantoms the limit was 21. Shaina's ingest-processor PR has 22 files directly in the phantom directory, which is why the phantom was added in #3306, caused CI to emit Too many items are being marked as part of a phantom this looks like a bug. (22), and had to be reverted twice.

What

  • Replaced the p == pathUri exact comparison with IsPhantomOrDescendant, which checks that the candidate URI shares the same scheme and host as the phantom and that its path starts with the phantom's path. This means a single phantom entry covers all files nested under that path.
  • Removed the skippedPhantoms counter and the > _phantoms.Count * 3 error guard entirely. The guard was a rough heuristic that fired on legitimate large TOC trees; with proper prefix matching there is no meaningful upper bound to enforce.

Order of operations for Shaina's work (after this merges)

Shaina is trying to move the processor reference docs from enrich-processor to ingest-processor (docs-content#1171). Her current approach (the "copy first" strategy in #3367) is:

  1. Merge this PR.
  2. Re-add the phantom — add elasticsearch://reference/ingest-processor back to the phantoms: section of navigation.yml in a small docs-builder PR and merge it.
  3. Merge elasticsearch#149537 — CI will now pass because the 22+ files under ingest-processor/ are covered by the phantom.
  4. Merge #3367 — moves the entry from phantoms: to toc: with a path_prefix, wiring up the new docs in the nav.
  5. Continue with the remaining steps (copy changes, add redirects, delist old enrich-processor, clean up stub).

Phantoms now correctly cover all descendants, not just direct children.
The hard cap on phantom-skipped files is removed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant