feat: lint legacy OS names

Author: youyongsong

.changeset/add-legacy-os-name-lint.md

@@ -0,0 +1,5 @@
+---
+"@alauda/doom": patch
+---
+
+Add a lint rule that flags legacy MicroOS and KubeOS names in documentation.

.prettierignore

@@ -1,4 +1,5 @@
 .yarn
+vendor
 **/pyodide
 # too big
 fixture-docs/shared/crds/operator.tekton.dev_*.yaml

eslint.config.js

@@ -15,6 +15,7 @@ export default defineConfig(
   {
     ignores: [
       'dist',
+      'vendor',
       '**/lib',
       '**/pyodide',
       // main language is en which is different with docs

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

@@ -15,6 +15,7 @@ export * from './no-empty-table-cell.ts'
 export * from './no-heading-punctuation.ts'
 export * from './no-heading-special-characters.ts'
 export * from './no-heading-sup-sub.ts'
+export * from './no-legacy-os-names.ts'
 export * from './no-multi-open-api-paths.ts'
 export * from './no-paragraph-indent.ts'
 export * from './no-unmatched-anchor.ts'

packages/doom/src/remark-lint/no-legacy-os-names.ts

@@ -0,0 +1,89 @@
+import type { Root } from 'mdast'
+import type {
+  MdxJsxAttribute,
+  MdxJsxAttributeValueExpression,
+} from 'mdast-util-mdx-jsx'
+import { lintRule } from 'unified-lint-rule'
+import { visitParents } from 'unist-util-visit-parents'
+
+const LEGACY_OS_NAME_REGEX =
+  /(?<![\p{L}\p{N}])(?:micro\s*os|micros|kube\s*os)(?![\p{L}\p{N}])/giu
+
+interface StringValueNode {
+  value: string
+  position?: Root['position']
+}
+
+const isStringValueNode = (node: unknown): node is StringValueNode =>
+  !!node &&
+  typeof node === 'object' &&
+  'value' in node &&
+  typeof node.value === 'string'
+
+const reportLegacyOSNames = (
+  value: string,
+  report: (legacyName: string) => void,
+) => {
+  for (const { 0: legacyName } of value.matchAll(LEGACY_OS_NAME_REGEX)) {
+    report(legacyName)
+  }
+}
+
+const createMessage = (legacyName: string) =>
+  `Unexpected legacy OS name "${legacyName}", use "Alauda OS" or "alauda os" instead`
+
+const getAttributeStringValue = (
+  value: MdxJsxAttribute['value'],
+): string | undefined => {
+  if (typeof value === 'string') {
+    return value
+  }
+
+  return (value as MdxJsxAttributeValueExpression).value
+}
+
+export const noLegacyOSNames = lintRule<Root>(
+  'doom-lint:no-legacy-os-names',
+  (root, vfile) => {
+    visitParents(root, (node, parents) => {
+      if (!isStringValueNode(node)) {
+        return
+      }
+
+      reportLegacyOSNames(node.value, (legacyName) => {
+        vfile.message(createMessage(legacyName), {
+          ancestors: [...parents, node],
+          place: node.position,
+        })
+      })
+    })
+
+    visitParents(
+      root,
+      ['mdxJsxFlowElement', 'mdxJsxTextElement'] as const,
+      (element, parents) => {
+        for (const attribute of element.attributes) {
+          if (
+            attribute.type !== 'mdxJsxAttribute' ||
+            typeof attribute.value === 'boolean' ||
+            attribute.value == null
+          ) {
+            continue
+          }
+
+          const value = getAttributeStringValue(attribute.value)
+          if (value == null) {
+            continue
+          }
+
+          reportLegacyOSNames(value, (legacyName) => {
+            vfile.message(createMessage(legacyName), {
+              ancestors: [...parents, element],
+              place: attribute.position,
+            })
+          })
+        }
+      },
+    )
+  },
+)

packages/doom/src/remarkrc.ts

@@ -16,6 +16,7 @@ import doomLint, {
   headingAnchorFormat,
   noDeepHeading,
   noDeepList,
+  noLegacyOSNames,
   noMultiOpenAPIPaths,
   noParagraphIndent,
   noUnmatchedAnchor,
@@ -41,6 +42,7 @@ export default {
     headingAnchorFormat,
     noDeepHeading,
     noDeepList,
+    noLegacyOSNames,
     noMultiOpenAPIPaths,
     noParagraphIndent,
     noUnmatchedAnchor,

packages/doom/test/remark-lint/no-legacy-os-names.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from '@rstest/core'
+
+import { lint, lintMdx } from './_helper.ts'
+
+import { noLegacyOSNames } from '#remark-lint/no-legacy-os-names.ts'
+
+describe('no-legacy-os-names', () => {
+  test('allows Alauda OS names and unrelated words', async () => {
+    const messages = await lint(
+      noLegacyOSNames,
+      [
+        'Alauda OS image',
+        'alauda os search query',
+        'AlaudaOS-Clone',
+        'microservices are unrelated',
+      ].join('\n'),
+    )
+
+    expect(messages).toHaveLength(0)
+  })
+
+  test('flags legacy OS names in markdown content', async () => {
+    const messages = await lint(
+      noLegacyOSNames,
+      [
+        '# MicroOS-Based Global Clusters',
+        '',
+        'Use Micro OS for x86.',
+        '',
+        '- micros global cluster',
+        '',
+        '| Source | Target |',
+        '|---|---|',
+        '| KubeOS | Alauda OS |',
+        '| Kube OS | Alauda OS |',
+        '',
+        '`kubeos-clone`',
+      ].join('\n'),
+    )
+
+    expect(messages).toHaveLength(6)
+    expect(messages.map(String).join('\n')).toContain('MicroOS')
+    expect(messages.map(String).join('\n')).toContain('Micro OS')
+    expect(messages.map(String).join('\n')).toContain('micros')
+    expect(messages.map(String).join('\n')).toContain('KubeOS')
+    expect(messages.map(String).join('\n')).toContain('Kube OS')
+    expect(messages.map(String).join('\n')).toContain('kubeos')
+  })
+
+  test('flags legacy OS names in frontmatter and code blocks', async () => {
+    const messages = await lint(
+      noLegacyOSNames,
+      [
+        '---',
+        'queries:',
+        '  - microos cluster path',
+        '---',
+        '',
+        '```yaml',
+        'name: kubeos-clone',
+        '```',
+      ].join('\n'),
+    )
+
+    expect(messages).toHaveLength(2)
+    expect(messages.map(String).join('\n')).toContain('microos')
+    expect(messages.map(String).join('\n')).toContain('kubeos')
+  })
+
+  test('flags legacy OS names in MDX string attributes', async () => {
+    const messages = await lintMdx(
+      noLegacyOSNames,
+      '<ExternalSiteLink children="MicroOS on Huawei DCS" />\n',
+    )
+
+    expect(messages).toHaveLength(1)
+    expect(String(messages[0])).toContain('MicroOS')
+  })
+})

tsconfig.json

@@ -17,6 +17,7 @@
       "path": "./packages/doom"
     }
   ],
+  "exclude": ["vendor"],
   "mdx": {
     "checkMdx": true
   }