feat: support linting site name usage

[JounQin]

Summary by CodeRabbit

• New Features

  • Added site name linting rule for validating MDX content against configured site names.

• Bug Fixes

  • Production environments now throw errors when site references are invalid instead of displaying warnings; non-production environments continue to display warnings for debugging purposes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: c2fd5d3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@alauda/doom	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

This PR introduces a new linting rule (doom:lint-site) that validates site name usage in MDX content against configured site names, integrates it into the remark pipeline, and modifies runtime error handling in external site components to throw exceptions in production when referenced sites are not found.

Changes

Cohort / File(s)	Summary
Changeset metadata .changeset/lucky-wolves-whisper.md	New changeset entry recording a patch release with a new feature for linting site name usage
Remark-lint rule implementation packages/doom/src/remark-lint/site.ts, packages/doom/src/remark-lint/index.ts	New linting rule that validates ExternalApisOverview, ExternalSite, and ExternalSiteLink elements have name attributes matching configured site names; lazy-loads and caches site configuration; exported via barrel index
Remark configuration packages/doom/src/remarkrc.ts	Integrates the new site linting rule into the remark plugin pipeline
Runtime error handling packages/doom/src/runtime/components/ExternalSiteLink.tsx, packages/doom/src/runtime/components/_ExternalSiteBase.tsx	Modified error handling to throw exceptions in production when referenced sites are not found, while showing warning directives in development

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix: api reference links #241: Modifies ExternalSiteLink.tsx runtime behavior and imports, related through shared component changes
• fix: base is not included in pathname #152: Also modifies ExternalSiteLink.tsx error handling and site data sourcing
• chore: cleanup remark lint rules #125: Modifies remark-lint setup in remarkrc configuration, related through shared linting pipeline integration

Suggested labels

feature, internal

Poem

🐰 A lint rule hops through MDX land,
Checking site names, oh so grand!
In production we stand tall and throw,
While dev shows warnings, letting coders know.
Sites validated from build to display! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: support linting site name usage' directly describes the main change—adding a new lint rule to validate site name attributes in MDX content.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

🧹 Recent nitpick comments

packages/doom/src/remark-lint/site.ts (1)

32-49: Consider also visiting mdxJsxTextElement nodes.

The rule only visits mdxJsxFlowElement, but ExternalSiteLink appears to be used inline within text (as seen in _ExternalSiteBase.tsx lines 29, 40, 50). Inline JSX elements are parsed as mdxJsxTextElement nodes, so these usages may not be linted.

♻️ Suggested fix to handle both element types

-  visitParents(root, 'mdxJsxFlowElement', (element, parents) => {
+  visitParents(root, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (element, parents) => {

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 310bfb8 and c2fd5d3.

📒 Files selected for processing (6)

• .changeset/lucky-wolves-whisper.md
• packages/doom/src/remark-lint/index.ts
• packages/doom/src/remark-lint/site.ts
• packages/doom/src/remarkrc.ts
• packages/doom/src/runtime/components/ExternalSiteLink.tsx
• packages/doom/src/runtime/components/_ExternalSiteBase.tsx

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{js,ts,tsx,jsx,json,yml,yaml,md}

📄 CodeRabbit inference engine (AGENTS.md)

Format code with Prettier according to the project's Prettier configuration

Files:

• packages/doom/src/remarkrc.ts
• packages/doom/src/runtime/components/_ExternalSiteBase.tsx
• packages/doom/src/remark-lint/index.ts
• packages/doom/src/runtime/components/ExternalSiteLink.tsx
• packages/doom/src/remark-lint/site.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript strict mode for type safety

Files:

• packages/doom/src/remarkrc.ts
• packages/doom/src/runtime/components/_ExternalSiteBase.tsx
• packages/doom/src/remark-lint/index.ts
• packages/doom/src/runtime/components/ExternalSiteLink.tsx
• packages/doom/src/remark-lint/site.ts

**/*.{js,ts,tsx,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Follow ESLint rules defined in eslint.config.js

Files:

• packages/doom/src/remarkrc.ts
• packages/doom/src/runtime/components/_ExternalSiteBase.tsx
• packages/doom/src/remark-lint/index.ts
• packages/doom/src/runtime/components/ExternalSiteLink.tsx
• packages/doom/src/remark-lint/site.ts

🧠 Learnings (6)

📚 Learning: 2025-07-09T02:31:06.588Z

Learnt from: JounQin
Repo: alauda/doom PR: 117
File: src/remark-lint/constants.ts:1-1
Timestamp: 2025-07-09T02:31:06.588Z
Learning: In the alauda/doom project, PUNCTUATION_REGEX in src/remark-lint/constants.ts is only used for test() operations, so the global flag is not needed and the current implementation /\p{P}/u is correct.

Applied to files:

• packages/doom/src/remarkrc.ts
• .changeset/lucky-wolves-whisper.md
• packages/doom/src/remark-lint/index.ts
• packages/doom/src/remark-lint/site.ts

📚 Learning: 2025-05-26T09:09:21.339Z

Learnt from: JounQin
Repo: alauda/doom PR: 30
File: src/runtime/components/K8sCrd.tsx:5-5
Timestamp: 2025-05-26T09:09:21.339Z
Learning: The alauda/doom project uses yarn v4 for dependency management, which handles package exports and module resolution correctly, so imports like `rspress/core/theme` work without any ESLint errors.

Applied to files:

• packages/doom/src/runtime/components/_ExternalSiteBase.tsx
• .changeset/lucky-wolves-whisper.md
• packages/doom/src/remark-lint/index.ts

📚 Learning: 2025-05-29T16:25:28.086Z

Learnt from: JounQin
Repo: alauda/doom PR: 40
File: src/plugins/sitemap/index.ts:7-7
Timestamp: 2025-05-29T16:25:28.086Z
Learning: In rspress/shared v2.0.0-beta.8, the '/logger' export is available in the package exports field, so imports like `import { logger } from 'rspress/shared/logger'` are valid even if ESLint shows resolution errors. This is used throughout the codebase in files like src/cli/translate.ts, src/cli/load-config.ts, src/utils/git.ts, and src/plugins/sitemap/index.ts.

Applied to files:

• packages/doom/src/runtime/components/_ExternalSiteBase.tsx
• packages/doom/src/remark-lint/index.ts
• packages/doom/src/runtime/components/ExternalSiteLink.tsx

📚 Learning: 2025-12-15T10:50:06.727Z

Learnt from: CR
Repo: alauda/doom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T10:50:06.727Z
Learning: Organize code in monorepo structure with workspaces: main tool in packages/doom/, export functionality in packages/export/, documentation in docs/, and test documentation in fixture-docs/

Applied to files:

• packages/doom/src/remark-lint/index.ts
• packages/doom/src/remark-lint/site.ts

📚 Learning: 2025-07-09T02:33:05.638Z

Learnt from: JounQin
Repo: alauda/doom PR: 117
File: src/remark-lint/no-heading-punctuation.ts:4-4
Timestamp: 2025-07-09T02:33:05.638Z
Learning: In the alauda/doom project, JounQin prefers to keep the `toString` import from `mdast-util-to-string` as is, even though it shadows the global toString property. Variable shadowing warnings for this specific case should not be flagged as issues.

Applied to files:

• packages/doom/src/remark-lint/index.ts

📚 Learning: 2025-05-26T08:59:41.491Z

Learnt from: JounQin
Repo: alauda/doom PR: 30
File: src/runtime/components/K8sCrd.tsx:5-5
Timestamp: 2025-05-26T08:59:41.491Z
Learning: In rspress/core v2.0.0-beta.7, the '/theme' export is available in the package exports field as `"./theme": { "default": "./theme.ts" }`, so imports like `import { Badge, Button } from 'rspress/core/theme'` are valid even if ESLint shows resolution errors.

Applied to files:

• packages/doom/src/remark-lint/index.ts

🧬 Code graph analysis (3)

packages/doom/src/remarkrc.ts (1)

packages/doom/src/remark-lint/site.ts (1)

• site (23-59)

packages/doom/src/runtime/components/ExternalSiteLink.tsx (1)

packages/doom/src/runtime/components/Directive.tsx (1)

• Directive (14-48)

packages/doom/src/remark-lint/site.ts (4)

packages/doom/src/cli/constants.ts (1)

• SITES_FILE (32-32)

packages/doom/src/shared/types.ts (1)

• DoomSite (3-10)

packages/doom/src/utils/fs.ts (1)

• pathExists (3-16)

packages/doom/src/utils/helpers.ts (1)

• resolveStaticConfig (18-36)

🔇 Additional comments (11)

.changeset/lucky-wolves-whisper.md (1)

1-5: LGTM!

The changeset correctly documents the new site linting feature as a patch release.

packages/doom/src/runtime/components/_ExternalSiteBase.tsx (2)

1-1: LGTM!

The isProduction import is correctly added to support the new conditional error handling.

---

109-115: No error boundaries found—this fail-fast pattern relies entirely on lint validation.

Throwing errors during React render in production will crash the component tree. Verification confirms no error boundaries exist in the codebase. The doom:lint-site rule validates site names at build time for ExternalSite, ExternalSiteLink, and ExternalApisOverview, making runtime errors unlikely. However, this is an intentional fail-fast approach with no safety net. Confirm this architectural choice is acceptable or add error boundary protection for graceful degradation.

packages/doom/src/runtime/components/ExternalSiteLink.tsx (2)

1-1: LGTM!

The isProduction import is correctly added.

---

40-46: Consistent error handling implementation.

The error handling pattern matches _ExternalSiteBase.tsx, maintaining consistency across both components. The development-time Directive provides a clear visual warning during authoring.

packages/doom/src/remark-lint/site.ts (4)

1-11: LGTM!

Imports are well-organized and appropriate for the lint rule implementation.

---

13-21: LGTM!

The element set and lazy-loaded config pattern are appropriate for the lint rule's use case.

---

23-30: LGTM!

The lazy loading pattern is efficient, and the empty array fallback when the config file doesn't exist is appropriate. The !sites?.length check on line 33 correctly handles edge cases where the file exists but is empty.

---

51-58: LGTM!

The error message is clear and actionable, correctly handling both string literal and expression attribute values. The position fallback logic provides accurate source locations.

packages/doom/src/remark-lint/index.ts (1)

17-17: LGTM!

The re-export follows the established barrel file pattern, making the new site lint rule accessible through the index.

packages/doom/src/remarkrc.ts (1)

19-19: LGTM!

The site lint rule is correctly imported and added to the plugins array, following the established alphabetical ordering convention. The integration pattern is consistent with other lint rules in this configuration.

Also applies to: 40-40

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

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 and usage tips.}

[pkg-pr-new]

Open in StackBlitz

yarn add https://pkg.pr.new/@alauda/doom@243.tgz

yarn add https://pkg.pr.new/@alauda/doom-export@243.tgz

commit: c2fd5d3

[Copilot]

Pull request overview

This PR adds linting capabilities for validating site name usage in external site components. The linter checks that site references in MDX components match valid sites defined in the sites.yaml configuration file.

Changes:

• Added a new remark lint rule to validate site name attributes in external site components
• Updated error handling to throw errors in production and show warnings in development for invalid site names
• Registered the new lint rule in the remark configuration

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/doom/src/runtime/components/_ExternalSiteBase.tsx	Updated error handling to throw in production for invalid site names
packages/doom/src/runtime/components/ExternalSiteLink.tsx	Updated error handling to throw in production for invalid site names
packages/doom/src/remarkrc.ts	Registered the new site name lint rule
packages/doom/src/remark-lint/site.ts	Implemented new lint rule to validate site names against sites.yaml
packages/doom/src/remark-lint/index.ts	Exported the new site lint rule
.changeset/lucky-wolves-whisper.md	Added changeset entry for this feature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.