docs(design): rewrite compilation context design document

[16bit-ykiko]

Summary

• Rewrite the compilation context design document (both zh and en) with clearer structure and accurate terminology
• New sections: "How the Compilation Context is Determined" (merging auto-resolution + LSP commands), "Header Context in Practice" (separated from concept definition), "Multi-Context in Indexing", FAQ
• Add concrete code examples: Debug/Release conditional compilation, X macro pattern for non-self-contained headers
• Add FAQ entries: multiple contexts from same host, -include equivalence with original compilation (citing C++ standard), disk vs virtual files, alternative "compile host and stop" approach
• Expand Known Limitations: self-contained detection automation, suffix handling, PCH sharing

Test plan

• Verify rendered markdown on GitHub
• Check cross-references to index-design.md and incremental.md

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d125b13a-130b-409a-89fc-384dfd10256a

📥 Commits

Reviewing files that changed from the base of the PR and between 4acd10c and 28d06d5.

📒 Files selected for processing (2)

• docs/en/design/compilation-context.md
• docs/zh/design/compilation-context.md

✅ Files skipped from review due to trivial changes (1)

• docs/en/design/compilation-context.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/zh/design/compilation-context.md

---

📝 Walkthrough

Walkthrough

The English and Chinese compilation-context docs were rewritten to define header and source contexts, describe prefix synthesis with #line and -include, explain merged indexing across contexts, and expand the limitations section.

Changes

Compilation Context Design Docs

Layer / File(s)	Summary
Context model and resolution docs/en/design/compilation-context.md, docs/zh/design/compilation-context.md	Defines source and header compilation contexts, formalizes header context as host source plus include position, and documents the context selection order from user choice through CDB and dependency-graph lookup.
Prefix synthesis and injection docs/en/design/compilation-context.md, docs/zh/design/compilation-context.md	Describes host discovery, include-chain traversal, prefix synthesis with #line, -include injection, and disk/session caching for synthesized prefixes.
Indexing and FAQ docs/en/design/compilation-context.md, docs/zh/design/compilation-context.md	Explains merged indexing across multiple header contexts and rewrites the FAQ content around -include, #line, and disk-backed synthesis.
Known limitations docs/en/design/compilation-context.md, docs/zh/design/compilation-context.md	Expands the limitations list with example-driven notes on self-contained detection, source switching, host selection, suffix handling, recursive includes, and PCH sharing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• clice-io/clice#468: Same design docs and compilation-context workflow were updated in a closely related change.

Poem

I hop through headers, neat and bright,
With #line stitched just right.
-include sings, the prefixes bloom,
Two docs now hum in rabbit-room. 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: a rewrite of the compilation context design document.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/design-updates

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/en/design/compilation-context.md`:
- Around line 28-38: The macro naming in the compilation-context example is
inconsistent: the `initialize()` snippet uses `#ifndef NDEBUG`, so update the
surrounding text to describe Debug/Release using the same standard convention.
Make the build flags and commentary match by referring to Release as `-DNDEBUG`
and Debug as the absence of `NDEBUG` (or an explicit `DEBUG` macro only if the
code also uses it), so the `conn->debug_label` and `log("connection created")`
example aligns with the documented build behavior.

In `@docs/zh/design/compilation-context.md`:
- Around line 28-38: The compilation-context example uses `#ifndef NDEBUG`, but
the surrounding text describes Debug builds as `-DDEBUG`, which conflicts with
the macro being checked. Update the `initialize()` example and its explanation
so the build flags and macro names are consistent, using the standard
`NDEBUG`/no-`NDEBUG` convention or changing the condition to match the
documented `DEBUG` flag across the `initialize()` snippet and the Debug/Release
description.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: aaea3b1c-3031-469a-9eef-42876d8cfadd

📥 Commits

Reviewing files that changed from the base of the PR and between f30e519 and 1a6ab9a.

📒 Files selected for processing (2)

• docs/en/design/compilation-context.md
• docs/zh/design/compilation-context.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1a6ab9a347

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 28d06d502a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".