feat: support linting site name usage

.changeset/lucky-wolves-whisper.md

@@ -0,0 +1,5 @@
+---
+"@alauda/doom": patch
+---
+
+feat: support linting site name usage

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

@@ -14,6 +14,7 @@ export * from './no-heading-punctuation.ts'
 export * from './no-heading-special-characters.ts'
 export * from './no-heading-sup-sub.ts'
 export * from './no-paragraph-indent.ts'
+export * from './site.ts'
 export * from './table-size.ts'
 export * from './unit-case.ts'
 

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

@@ -0,0 +1,59 @@
+import path from 'node:path'
+
+import type { Root } from 'mdast'
+import type { MdxJsxAttribute } from 'mdast-util-mdx-jsx'
+import { lintRule } from 'unified-lint-rule'
+import { visitParents } from 'unist-util-visit-parents'
+
+import { SITES_FILE } from '../cli/constants.ts'
+import type { DoomSite } from '../shared/types.ts'
+import { pathExists } from '../utils/fs.ts'
+import { resolveStaticConfig } from '../utils/helpers.ts'
+
+const SITE_ELEMENTS = new Set([
+  'ExternalApisOverview',
+  'ExternalSite',
+  'ExternalSiteLink',
+])
+
+const sitesConfigFilePath = path.resolve(SITES_FILE)
+
+let sites: DoomSite[] | undefined
+
+export const site = lintRule<Root>('doom:lint-site', async (root, vfile) => {
+  if (!sites) {
+    if (await pathExists(sitesConfigFilePath, 'file')) {
+      sites = await resolveStaticConfig<DoomSite[]>(sitesConfigFilePath)
+    } else {
+      sites = []
+    }
+  }
+
+  visitParents(root, 'mdxJsxFlowElement', (element, parents) => {
+    if (!sites?.length || !element.name || !SITE_ELEMENTS.has(element.name)) {
+      return
+    }
+
+    const nameAttr = element.attributes.find(
+      (attr): attr is MdxJsxAttribute =>
+        attr.type === 'mdxJsxAttribute' && attr.name === 'name',
+    )
+
+    const nameVal = nameAttr?.value
+
+    if (
+      typeof nameVal === 'string' &&
+      sites.some((site) => site.name === nameVal)
+    ) {
+      return
+    }
+
+    vfile.message(
+      `Invalid site \`name\` property value \`${typeof nameVal === 'string' ? nameVal : nameVal?.value}\` which should be static string matching a site name from \`${SITES_FILE}\` config.`,
+      {
+        ancestors: [...parents, element],
+        place: (nameAttr ?? element).position,
+      },
+    )
+  })
+})

packages/doom/src/remarkrc.ts

@@ -16,6 +16,7 @@ import doomLint, {
   noDeepHeading,
   noDeepList,
   noParagraphIndent,
+  site,
   tableSize,
   unitCase,
 } from './remark-lint/index.ts'
@@ -36,6 +37,7 @@ export default {
     noDeepHeading,
     noDeepList,
     noParagraphIndent,
+    site,
     tableSize,
     unitCase,
   ],

packages/doom/src/runtime/components/ExternalSiteLink.tsx

@@ -1,4 +1,4 @@
-import { useLang, useSite } from '@rspress/core/runtime'
+import { isProduction, useLang, useSite } from '@rspress/core/runtime'
 import {
   addTrailingSlash,
   isExternalUrl,
@@ -38,12 +38,11 @@ const ExternalSiteLink_ = ({
   const lang = useLang()
 
   if (!site) {
-    return (
-      <Directive type="danger">
-        No site with name `{name}` found, please ensure it's already defined at
-        `sites.yaml`
-      </Directive>
-    )
+    const message = `No site with name \`${name}\` found, please ensure it's already defined at \`sites.yaml\``
+    if (isProduction()) {
+      throw new Error(message)
+    }
+    return <Directive type="danger">{message}</Directive>
   }
 
   if (isExternalUrl(href)) {

packages/doom/src/runtime/components/_ExternalSiteBase.tsx

@@ -1,4 +1,4 @@
-import { useLang } from '@rspress/core/runtime'
+import { isProduction, useLang } from '@rspress/core/runtime'
 import virtual from 'doom-@global-virtual'
 import { type FC, useMemo } from 'react'
 
@@ -107,12 +107,11 @@ export const ExternalSiteBase = ({ name, template }: ExternalSiteBaseProps) => {
   )
 
   if (!site) {
-    return (
-      <Directive type="danger">
-        No site with name `{name}` found, please ensure it's already defined at
-        `sites.yaml`
-      </Directive>
-    )
+    const message = `No site with name \`${name}\` found, please ensure it's already defined at \`sites.yaml\``
+    if (isProduction()) {
+      throw new Error(message)
+    }
+    return <Directive type="danger">{message}</Directive>
   }
 
   const Notes = template === 'apisOverview' ? ApisOverviewNotes : SiteNotes