Fix site name and git info when --path points to docs subfolder

[Mpdreamz]

Why

Running docs-builder serve --path ~/project/docs/ showed unknown-docs as the site title and an empty branch/commit panel instead of the repository name and branch.

Root cause (original bug): Paths.FindGitRoot(DocumentationSourceDirectory, ceiling: rootFolder). When --path points to the docs subfolder, rootFolder == docsPath so the ceiling locked the git-root walk inside that folder and could never see .git one level up — CheckoutDirectory was null, git info was Unavailable, and the name fell back to unknown-docs.

Root cause (design): FileSystemFactory exposed ambient statics (RealRead, RealWrite, AppData) that any code could reach for without declaring the dependency in its signature. The documentation scope depends on --path and --output, which are per-invocation — a singleton can never supply it correctly. Every command that called FileSystemFactory.RealRead silently coupled itself to the process CWD, making the scope invisible and untestable.

The statics also made the read/write distinction unenforceable. BuildContext.ReadFileSystem and BuildContext.WriteFileSystem were both typed ScopedFileSystem — a type that says "something scoped me" and nothing more. Nothing in the type system prevented passing a read scope as a write scope, and several test sites did exactly that. Git checkout resolution was scattered across three divergent implementations that could disagree on where the checkout was.

What

Strongly-typed, intent-carrying filesystems

The core idea: a type that accepts ScopedFileSystem accepts any scope. A caller looking at a ScopedFileSystem parameter has no idea whether it expects a read scope, a write scope, or whether .git access is allowed. The name in the variable — readFs, writeFs — is the only signal, and names aren't checked by the compiler.

Named subclasses fix this. A parameter typed DocumentationWriteFileSystem rejects a read scope at compile time. A parameter typed CheckoutsFileSystem can't be satisfied by a DocumentationFileSystem for a single docs set. The type carries the intent the bare ScopedFileSystem could not.

Call-site types — what consumers construct and pass around:

Class	Where	Use case
DocumentationFileSystem	src/Elastic.Documentation.Tooling/FileSystems/	The entry point. Constructed via DocumentationFileSystem.Resolve(invocation, options). Runs the six-step bootstrap (invocation → docset anchor → checkout → git dirs → git info → output), exposes the result as .Paths, and is the read scope. Callers use it as fs.Read and fs.Write — .Read is the instance itself; .Write is a DocumentationWriteFileSystem produced during construction, never separately instantiated.
DocumentationWriteFileSystem	src/Elastic.Documentation/FileSystems/	An artifact of constructing DocumentationFileSystem, accessed via .Write. Same checkout roots as .Read but .git is excluded from the allowlist — writing into .git is structurally impossible. Because both scopes come from the same ResolvedDocumentationPaths, read and write can never disagree about the checkout or output path.
CheckoutsFileSystem	src/Elastic.Documentation.Tooling/FileSystems/	Scope over a directory of cloned repositories. Used by the assembler, which operates on a tree of clones rather than a single documentation set. No docset anchoring, no git resolution. Exposes .Read (itself) and .Write following the same pattern.
ApplicationDataFileSystem	src/Elastic.Documentation.Tooling/FileSystems/	Scope over the OS application-data directory. Used for the codex link-index clone. No per-invocation inputs.

Bootstrap helpers — instantiated internally by DocumentationPathsResolver, not by callers:

Class	Where	Role
DocsetScanFileSystem	src/Elastic.Documentation.Tooling/FileSystems/	Rooted at the invocation path, nothing above it. Locates docset.yml/_docset.yml in steps 1–2 without escaping the invocation root. Discarded once the anchor is found.
GitResolveFileSystem	src/Elastic.Documentation.Tooling/FileSystems/	Rooted maxParents above the docset anchor (not the invocation). Walks up to .git and reads config/HEAD from resolved git directories, including worktree commondir targets outside the anchor's ancestry, in steps 3–5. Discarded once git info is resolved.

Statics removed

FileSystemFactory.RealRead, RealWrite, and AppData are gone. Statics made the filesystem dependency invisible in signatures — a type that reached for FileSystemFactory.RealRead declared no dependency and could not be tested with a mock. Because the documentation scope is per-invocation (depends on --path and --output), a singleton was always wrong: it hardcoded the process CWD as the checkout root, which is exactly the bug that caused --path repo/docs to show unknown-docs.

With the statics gone, every consumer that wants a filesystem must declare it. The dependency is visible, the scope is per-invocation, and the type tells the reader what the scope is for.

Missing .git is now a hard error with a remedy

Previously, failing to find .git silently produced a null CheckoutDirectory, which then caused the name fallback to unknown-docs and empty git info downstream — the symptom was observable only at render time with no pointer to the cause.

Now DocumentationPathsResolver throws DocumentationPathException immediately:

No .git found at '/path/to/docs' or within 1 parent directory(ies).
Pass --git-dir to point at the repository's .git directory explicitly.

The message names the flag that fixes it. --git-dir accepts the path to the .git directory; its parent becomes the checkout. Worktrees are handled automatically through commondir — --git-dir should point at the worktree's own .git file's location, not the shared object store.

Ordered six-step bootstrap (DocumentationPathsResolver)

Previously scattered across BuildContext's constructor, FileSystemFactory, and three separate git-resolution paths. Now a single static class with one method per step, each creating its own minimal scope and discarding it:

1. Invocation path — the --path argument or CWD.
2. Docset anchor — scan from invocation for docset.yml/_docset.yml (skipped when ConfigurationFile is pre-supplied). Uses DocsetScanFileSystem.
3. Checkout — --git-dir?.Parent ?? FindGitRoot(anchor, maxParents) ?? hard error naming --git-dir. Uses GitResolveFileSystem.
4. Git directories — the real .git path(s) needed in scope. For worktrees: checkout/.git (pointer file) + the commondir target resolved via the unscoped inner filesystem.
5. Git info — GitCheckoutInformationFactory.Create through a scope widened by step 4. Or DocumentationScopeOptions.Git if the caller pre-computed it (Assembler, Codex).
6. Output — --output argument or checkout/.artifacts/docs/html (anchored at the checkout, never the invocation, so --path /repo and --path /repo/docs both write to /repo/.artifacts).

BuildContext simplification

Stores one DocumentationFileSystem and computes ReadFileSystem, WriteFileSystem, DocumentationSourceDirectory, DocumentationCheckoutDirectory, ConfigurationPath, OutputDirectory, and Git as projections of .Paths. Nothing is copied independently, so nothing can drift out of agreement. The legacy ScopedFileSystem pair constructor is deleted; all seven src/ callers are migrated to DocumentationFileSystem.Resolve.

Worktree resolution fix

ResolveGitDirectories now uses the unscoped inner filesystem for commondir traversal, because the main .git directory lies outside the gitScope root by design. Explicit --git-dir injects its path into gitDirectories directly so the factory scope covers it.

Test plan

• DocumentationPathsResolverTests — 21 new tests:
  • Normal repo: --path /repo and --path /repo/docs → same CheckoutDirectory and SourceDirectory
  • Regular repo git info (branch, ref, repository name)
  • Worktree: checkout = worktree root, GitDirectories includes the .git pointer path and resolved commondir target, git info resolved from main .git
  • Worktree + --path /worktree/docs → same checkout as --path /worktree
  • Explicit --git-dir: checkout = gitDir.Parent, git info from overridden dir
  • Mock FS without .git: graceful fallback, checkout = source, Git override preserved
  • Output defaults to checkout/.artifacts (regression guard: same for --path /repo and --path /repo/docs)
  • Explicit --output override respected
  • Pre-discovered ConfigurationFile skips docset scan
  • No docset → DocumentationPathException
  • DocumentationFileSystem.Resolve integration for regular repo and worktree
• GitCheckoutResolutionTests — regular repo, detached HEAD, worktree absolute/relative gitdir, commondir, missing gitdir, canned-fallback guard
• FindGitRootTests — maxParents cases, worktree pointer
• BuildContextDocumentationCheckoutDirectoryTests — --path /repo and --path /repo/docs converge
• ./build.sh unit-test — 4332 tests pass (0 failures)
• ./build.sh lint — clean
• serve --path ~/Projects/docs-eng-team/docs — header shows repo name, branch/commit populated
• serve --path ~/Projects/docs-eng-team/ — identical to above
• serve from inside the repo — identical
• Repeat above in a git worktree checkout

🤖 Generated with Claude Code
https://claude.ai/code/session_01PC5GiyZKhreYSqf2grz7pi