@alauda/doom 2.5.3 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/lib/cli/api.d.ts +2 -0
  2. package/lib/cli/api.js +147 -0
  3. package/lib/cli/helpers.d.ts +1 -7
  4. package/lib/cli/helpers.js +4 -41
  5. package/lib/cli/index.js +2 -0
  6. package/lib/cli/translate-agent.d.ts +81 -0
  7. package/lib/cli/translate-agent.js +450 -0
  8. package/lib/cli/translate-check.d.ts +17 -0
  9. package/lib/cli/translate-check.js +67 -0
  10. package/lib/cli/translate-checker.d.ts +58 -0
  11. package/lib/cli/translate-checker.js +112 -0
  12. package/lib/cli/translate-judge.d.ts +119 -0
  13. package/lib/cli/translate-judge.js +224 -0
  14. package/lib/cli/translate-limits.d.ts +43 -0
  15. package/lib/cli/translate-limits.js +55 -0
  16. package/lib/cli/translate-mask.d.ts +144 -0
  17. package/lib/cli/translate-mask.js +617 -0
  18. package/lib/cli/translate-models.d.ts +127 -0
  19. package/lib/cli/translate-models.js +189 -0
  20. package/lib/cli/translate-scratch.d.ts +142 -0
  21. package/lib/cli/translate-scratch.js +187 -0
  22. package/lib/cli/translate-terms.d.ts +22 -0
  23. package/lib/cli/translate-terms.js +33 -0
  24. package/lib/cli/translate.d.ts +15 -10
  25. package/lib/cli/translate.js +228 -185
  26. package/lib/eslint.js +48 -5
  27. package/lib/plugins/api/index.js +1 -1
  28. package/lib/plugins/api/types.d.ts +36 -1
  29. package/lib/plugins/global/components.d.ts +18 -0
  30. package/lib/plugins/global/components.js +33 -0
  31. package/lib/plugins/global/index.js +2 -10
  32. package/lib/remark-lint/index.d.ts +20 -0
  33. package/lib/remark-lint/index.js +40 -0
  34. package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
  35. package/lib/remark-lint/no-unmatched-anchor.js +13 -0
  36. package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
  37. package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
  38. package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
  39. package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
  40. package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
  41. package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
  42. package/lib/remark-lint/rule-sets.d.ts +75 -0
  43. package/lib/remark-lint/rule-sets.js +120 -0
  44. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  45. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  46. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  47. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  48. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  49. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  50. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  51. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  52. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  53. package/lib/remark-lint/translation-parity/index.js +24 -0
  54. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  55. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  56. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  57. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  58. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +26 -0
  59. package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
  60. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  61. package/lib/remark-lint/translation-parity/shared.js +282 -0
  62. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  63. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  64. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  65. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  66. package/lib/remark-lint/translation-parity/url-residue.d.ts +2 -0
  67. package/lib/remark-lint/translation-parity/url-residue.js +46 -0
  68. package/lib/remarkrc.d.ts +1 -1
  69. package/lib/remarkrc.js +7 -34
  70. package/lib/runtime/api-paths.d.ts +20 -0
  71. package/lib/runtime/api-paths.js +29 -0
  72. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  73. package/lib/runtime/components/K8sAPI.js +49 -10
  74. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  75. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  76. package/lib/runtime/components/OpenAPIPath.js +19 -2
  77. package/lib/runtime/components/_HeadingTitle.js +24 -6
  78. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  79. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  80. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  81. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  82. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  83. package/lib/runtime/components/_translation-policy.js +32 -0
  84. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  85. package/lib/runtime/translation.d.ts +68 -0
  86. package/lib/runtime/translation.js +51 -0
  87. package/lib/runtime/utils.d.ts +24 -2
  88. package/lib/runtime/utils.js +87 -5
  89. package/lib/shared/constants.d.ts +9 -0
  90. package/lib/shared/constants.js +14 -0
  91. package/lib/types.d.ts +70 -0
  92. package/lib/utils/helpers.js +8 -2
  93. package/package.json +3 -1
package/lib/eslint.js CHANGED
@@ -1,4 +1,6 @@
1
+ import fs from 'node:fs';
1
2
  import { createRequire } from 'node:module';
3
+ import path from 'node:path';
2
4
  import { fileURLToPath } from 'node:url';
3
5
  import cspellRecommended from '@cspell/eslint-plugin/recommended';
4
6
  import js from '@eslint/js';
@@ -9,14 +11,34 @@ import * as mdx from 'eslint-plugin-mdx';
9
11
  import globals from 'globals';
10
12
  import tseslint from 'typescript-eslint';
11
13
  import { loadConfig } from './cli/load-config.js';
14
+ import { getGlobalComponentNames } from './plugins/global/components.js';
15
+ import { SUPPORTED_LANGUAGES } from './shared/index.js';
16
+ import { pkgResolve } from './utils/index.js';
12
17
  const cjsRequire = createRequire(import.meta.url);
13
18
  let remarkConfigPath;
19
+ const isLoadableRemarkConfigPath = (filepath) => ['.cjs', '.js', '.mjs'].includes(path.extname(filepath));
14
20
  try {
15
- remarkConfigPath = fileURLToPath(import.meta.resolve('./remarkrc.js'));
21
+ const resolvedRemarkConfigPath = fileURLToPath(import.meta.resolve('./remarkrc.js'));
22
+ if (isLoadableRemarkConfigPath(resolvedRemarkConfigPath)) {
23
+ remarkConfigPath = resolvedRemarkConfigPath;
24
+ }
16
25
  }
17
26
  catch {
18
- remarkConfigPath = cjsRequire.resolve('./remarkrc.js');
27
+ try {
28
+ const resolvedRemarkConfigPath = cjsRequire.resolve('./remarkrc.js');
29
+ if (isLoadableRemarkConfigPath(resolvedRemarkConfigPath)) {
30
+ remarkConfigPath = resolvedRemarkConfigPath;
31
+ }
32
+ }
33
+ catch {
34
+ remarkConfigPath = undefined;
35
+ }
36
+ }
37
+ const builtRemarkConfigPath = pkgResolve('lib/remarkrc.js');
38
+ if (!remarkConfigPath && fs.existsSync(builtRemarkConfigPath)) {
39
+ remarkConfigPath = builtRemarkConfigPath;
19
40
  }
41
+ const globalComponentGlobals = Object.fromEntries(getGlobalComponentNames().map((name) => [name, 'readonly']));
20
42
  async function doom(userConfigOrRoot) {
21
43
  let cspellOptions;
22
44
  let config;
@@ -48,13 +70,31 @@ async function doom(userConfigOrRoot) {
48
70
  },
49
71
  },
50
72
  {
73
+ // Every language directory, not just the one documents are written in.
74
+ // The remark config is what carries doom's lint rules, so scoping it to
75
+ // the source language meant a translated document was parsed and then
76
+ // checked against nothing: a lint run over `zh/` reported success having
77
+ // applied no rule at all.
78
+ //
79
+ // Still scoped to language directories rather than to every markdown file
80
+ // in the repository — changesets, READMEs and design notes are not
81
+ // documentation pages and do not want documentation rules.
82
+ files: [
83
+ `**/{${SUPPORTED_LANGUAGES.join(',')}}/**/*.{js,jsx,md,mdx,ts,tsx}`,
84
+ ],
85
+ languageOptions: {
86
+ parserOptions: {
87
+ ...(remarkConfigPath && { remarkConfigPath }),
88
+ },
89
+ },
90
+ },
91
+ {
92
+ // Spell checking stays scoped to the source language: the dictionaries
93
+ // are for it, and running them over a translation is noise.
51
94
  files: [`**/${config?.lang ?? 'en'}/**/*.{js,jsx,md,mdx,ts,tsx}`],
52
95
  extends: cspellEnabled ? [cspellRecommended] : [],
53
96
  languageOptions: {
54
97
  globals: globals.browser,
55
- parserOptions: {
56
- remarkConfigPath,
57
- },
58
98
  },
59
99
  rules: cspellEnabled
60
100
  ? {
@@ -67,6 +107,9 @@ async function doom(userConfigOrRoot) {
67
107
  },
68
108
  {
69
109
  files: ['**/*.mdx'],
110
+ languageOptions: {
111
+ globals: globalComponentGlobals,
112
+ },
70
113
  rules: {
71
114
  '@eslint-react/jsx-no-children-prop': 'off',
72
115
  '@eslint-react/rules-of-hooks': 'off',
@@ -6,7 +6,7 @@ export const apiPlugin = ({ localBasePath, }) => {
6
6
  name: 'doom-api',
7
7
  async addRuntimeModules(config, isProd) {
8
8
  return {
9
- 'doom-@api-virtual': `export default ${JSON.stringify({ references: config.api?.references, pathPrefix: config.api?.pathPrefix }, null, isProd ? 0 : 2)}`,
9
+ 'doom-@api-virtual': `export default ${JSON.stringify({ references: config.api?.references, pathPrefix: config.api?.pathPrefix, crdVersion: config.api?.crdVersion }, null, isProd ? 0 : 2)}`,
10
10
  ...(await generateRuntimeModule(config.api?.crds, 'api-crds', config.root, localBasePath, isProd)),
11
11
  ...(await generateRuntimeModule(config.api?.openapis, 'api-openapis', config.root, localBasePath, isProd, async (doc) => {
12
12
  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -3,8 +3,34 @@ export interface ApiPluginOptions {
3
3
  localBasePath: string;
4
4
  crds?: string[];
5
5
  openapis?: string[];
6
- references?: Record<string, string>;
6
+ /**
7
+ * Map a schema ref name to how it should be linked / whether it is documented
8
+ * elsewhere. A plain string is the link href (backward compatible). The object
9
+ * form separates the two roles a value plays:
10
+ *
11
+ * - `href`: where a `RefLink` to this schema points.
12
+ * - `routePath`: the page that documents this schema inline. On that page the
13
+ * schema is expanded; elsewhere it is only linked. `false` disables the
14
+ * omit entirely (always link, never expand) — the explicit form of the
15
+ * `.html`-href trick.
16
+ */
17
+ references?: Record<string, string | {
18
+ href: string;
19
+ routePath?: string | false;
20
+ }>;
7
21
  pathPrefix?: string;
22
+ /**
23
+ * Which version of a multi-version CRD to render by default when a page does
24
+ * not pass an explicit `apiVersion` prop.
25
+ *
26
+ * - `preferred` (default): the version `kubectl` resolves to — highest
27
+ * priority among `served` versions (GA > beta > alpha).
28
+ * - `storage`: the etcd storage version (`storage: true`).
29
+ * - `first`: legacy behavior — `spec.versions[0]`.
30
+ *
31
+ * @default 'preferred'
32
+ */
33
+ crdVersion?: 'preferred' | 'storage' | 'first';
8
34
  }
9
35
  export interface CustomResourceDefinitionVersion {
10
36
  name: string;
@@ -13,6 +39,15 @@ export interface CustomResourceDefinitionVersion {
13
39
  };
14
40
  served: boolean;
15
41
  storage: boolean;
42
+ /**
43
+ * Subresources the API server actually exposes for this version. `/status`
44
+ * and `/scale` endpoints exist if and only if they are declared here — not
45
+ * because the schema happens to contain a `status` property.
46
+ */
47
+ subresources?: {
48
+ status?: object;
49
+ scale?: object;
50
+ };
16
51
  }
17
52
  export interface CustomResourceDefinition {
18
53
  apiVersion: string;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Whether a file in `runtime/components/` becomes a global MDX component.
3
+ *
4
+ * The filename is the identifier: it is emitted as `import <basename> from …`
5
+ * into every document of every site doom builds. Two consequences, and both
6
+ * have bitten:
7
+ *
8
+ * - the basename must be a valid JS identifier — a hyphen in it is a syntax
9
+ * error in every document, not a naming nit;
10
+ * - it must start with an uppercase letter, or MDX reads it as an HTML tag.
11
+ *
12
+ * A module that lives here for proximity but is *not* a component — shared
13
+ * constants, helpers — opts out with a `_` prefix, the way `_utils.ts` always
14
+ * has. `test/plugins/global/components.spec.ts` enforces both halves.
15
+ */
16
+ export declare const isGlobalComponentFile: (file: string) => boolean;
17
+ export declare const getGlobalComponentFiles: () => string[];
18
+ export declare const getGlobalComponentNames: () => string[];
@@ -0,0 +1,33 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { baseResolve } from "../../utils/index.js";
4
+ const componentsDir = baseResolve('runtime/components');
5
+ /**
6
+ * Whether a file in `runtime/components/` becomes a global MDX component.
7
+ *
8
+ * The filename is the identifier: it is emitted as `import <basename> from …`
9
+ * into every document of every site doom builds. Two consequences, and both
10
+ * have bitten:
11
+ *
12
+ * - the basename must be a valid JS identifier — a hyphen in it is a syntax
13
+ * error in every document, not a naming nit;
14
+ * - it must start with an uppercase letter, or MDX reads it as an HTML tag.
15
+ *
16
+ * A module that lives here for proximity but is *not* a component — shared
17
+ * constants, helpers — opts out with a `_` prefix, the way `_utils.ts` always
18
+ * has. `test/plugins/global/components.spec.ts` enforces both halves.
19
+ */
20
+ export const isGlobalComponentFile = (file) => {
21
+ const basename = path.basename(file, path.extname(file));
22
+ return (!basename.startsWith('_') &&
23
+ !basename.endsWith('.d') &&
24
+ basename !== 'index');
25
+ };
26
+ export const getGlobalComponentFiles = () => fs
27
+ .readdirSync(componentsDir)
28
+ .filter(isGlobalComponentFile)
29
+ .map((file) => path.resolve(componentsDir, file));
30
+ export const getGlobalComponentNames = () => fs
31
+ .readdirSync(componentsDir)
32
+ .filter(isGlobalComponentFile)
33
+ .map((file) => path.basename(file, path.extname(file)));
@@ -3,8 +3,8 @@ import path from 'node:path';
3
3
  import { addTrailingSlash } from '@rspress/shared';
4
4
  import { ACP_BASE } from "../../shared/index.js";
5
5
  import { baseResolve, pkgResolve } from "../../utils/index.js";
6
+ import { getGlobalComponentFiles } from "./components.js";
6
7
  const globalComponentsDir = baseResolve('global');
7
- const componentsDir = baseResolve('runtime/components');
8
8
  export const globalPlugin = ({ version, download, }) => {
9
9
  return {
10
10
  name: 'doom-global',
@@ -13,15 +13,7 @@ export const globalPlugin = ({ version, download, }) => {
13
13
  .readdirSync(globalComponentsDir, 'utf8')
14
14
  .map((component) => path.resolve(globalComponentsDir, component)),
15
15
  markdown: {
16
- globalComponents: fs
17
- .readdirSync(componentsDir)
18
- .filter((file) => {
19
- const basename = path.basename(file, path.extname(file));
20
- return (!basename.startsWith('_') &&
21
- !basename.endsWith('.d') &&
22
- basename !== 'index');
23
- })
24
- .map((file) => path.resolve(componentsDir, file)),
16
+ globalComponents: getGlobalComponentFiles(),
25
17
  },
26
18
  addRuntimeModules(config, isProd) {
27
19
  return {
@@ -1,5 +1,6 @@
1
1
  import type { Root } from 'mdast';
2
2
  import type { Plugin } from 'unified';
3
+ import type { VFile } from 'vfile';
3
4
  export * from './check-dead-links.ts';
4
5
  export * from './file-naming.ts';
5
6
  export * from './heading-anchor-format.ts';
@@ -17,9 +18,28 @@ export * from './no-legacy-os-names.ts';
17
18
  export * from './no-multi-open-api-paths.ts';
18
19
  export * from './no-paragraph-indent.ts';
19
20
  export * from './no-unmatched-anchor.ts';
21
+ export * from './no-unopened-frontmatter.ts';
22
+ export * from './no-unparsed-emphasis.ts';
23
+ export * from './no-unresolved-api-ref.ts';
20
24
  export * from './site.ts';
21
25
  export * from './table-size.ts';
22
26
  export * from './title-required.ts';
27
+ export * from './translation-parity/index.ts';
23
28
  export * from './unit-case.ts';
24
29
  declare const doomLint: Plugin<[], Root>;
30
+ /**
31
+ * Drops the Chinese-typography rules' messages on documents that are not
32
+ * Chinese.
33
+ *
34
+ * Filtering afterwards rather than not running the rules is deliberate: the
35
+ * rules are third-party plugins with no notion of language, and message control
36
+ * already establishes that filtering `file.messages` is how this rule set
37
+ * expresses "this does not apply here".
38
+ *
39
+ * A document whose language cannot be told from its path keeps its messages —
40
+ * not knowing is a reason to report, not a reason to go quiet.
41
+ */
42
+ export declare const dropChineseTypographyMessages: (file: VFile) => void;
43
+ /** Must come after the rules it filters. */
44
+ export declare const chineseTypographyOnlyInChinese: Plugin<[], Root>;
25
45
  export default doomLint;
@@ -16,9 +16,13 @@ export * from "./no-legacy-os-names.js";
16
16
  export * from "./no-multi-open-api-paths.js";
17
17
  export * from "./no-paragraph-indent.js";
18
18
  export * from "./no-unmatched-anchor.js";
19
+ export * from "./no-unopened-frontmatter.js";
20
+ export * from "./no-unparsed-emphasis.js";
21
+ export * from "./no-unresolved-api-ref.js";
19
22
  export * from "./site.js";
20
23
  export * from "./table-size.js";
21
24
  export * from "./title-required.js";
25
+ export * from "./translation-parity/index.js";
22
26
  export * from "./unit-case.js";
23
27
  const doomLint = function () {
24
28
  this.use(() => remarkMessageControl({
@@ -26,4 +30,40 @@ const doomLint = function () {
26
30
  source: ['doom-lint', 'remark-lint'],
27
31
  }));
28
32
  };
33
+ /**
34
+ * Rules about Chinese typography, which only mean anything on a Chinese
35
+ * document.
36
+ *
37
+ * They came into the rule set when the only documents anyone linted were
38
+ * Chinese. Once translations are linted too they read `pod’ами` — Russian
39
+ * declining a Latin word, which is how Russian does it — as an unmatched
40
+ * quotation mark, and report every page that uses one.
41
+ */
42
+ const CHINESE_ONLY_RULES = new Set([
43
+ 'match-punctuation',
44
+ 'no-chinese-punctuation-in-number',
45
+ ]);
46
+ const CHINESE_DOCUMENT = /(?:^|[\\/])zh[\\/]/;
47
+ /**
48
+ * Drops the Chinese-typography rules' messages on documents that are not
49
+ * Chinese.
50
+ *
51
+ * Filtering afterwards rather than not running the rules is deliberate: the
52
+ * rules are third-party plugins with no notion of language, and message control
53
+ * already establishes that filtering `file.messages` is how this rule set
54
+ * expresses "this does not apply here".
55
+ *
56
+ * A document whose language cannot be told from its path keeps its messages —
57
+ * not knowing is a reason to report, not a reason to go quiet.
58
+ */
59
+ export const dropChineseTypographyMessages = (file) => {
60
+ if (!file.path || CHINESE_DOCUMENT.test(file.path)) {
61
+ return;
62
+ }
63
+ file.messages = file.messages.filter((message) => !CHINESE_ONLY_RULES.has(message.ruleId ?? ''));
64
+ };
65
+ /** Must come after the rules it filters. */
66
+ export const chineseTypographyOnlyInChinese = () => (_tree, file) => {
67
+ dropChineseTypographyMessages(file);
68
+ };
29
69
  export default doomLint;
@@ -1,2 +1,12 @@
1
1
  import type { Root } from 'mdast';
2
+ /**
3
+ * Forget what this document looked like the last time it was linted.
4
+ *
5
+ * Both caches key on a path and assume a path names one fixed document, which
6
+ * holds for a lint run over a directory. The translator breaks that assumption:
7
+ * it checks the same target path once per repair turn, with different content
8
+ * each time. Without this, turn 2 is judged against turn 1's anchors — a red
9
+ * that no amount of repairing can clear, because the repair is invisible.
10
+ */
11
+ export declare const forgetDocumentAnchors: (filepath: string) => void;
2
12
  export declare const noUnmatchedAnchor: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -10,6 +10,19 @@ import { mdProcessor, mdxProcessor } from "../plugins/index.js";
10
10
  import { getConfig } from "./utils.js";
11
11
  const anchorsCache = new Map();
12
12
  const astCache = new Map();
13
+ /**
14
+ * Forget what this document looked like the last time it was linted.
15
+ *
16
+ * Both caches key on a path and assume a path names one fixed document, which
17
+ * holds for a lint run over a directory. The translator breaks that assumption:
18
+ * it checks the same target path once per repair turn, with different content
19
+ * each time. Without this, turn 2 is judged against turn 1's anchors — a red
20
+ * that no amount of repairing can clear, because the repair is invisible.
21
+ */
22
+ export const forgetDocumentAnchors = (filepath) => {
23
+ anchorsCache.delete(filepath);
24
+ astCache.delete(filepath);
25
+ };
13
26
  const getAnchors = (filepath) => {
14
27
  if (anchorsCache.has(filepath)) {
15
28
  return anchorsCache.get(filepath);
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const noUnopenedFrontmatter: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,70 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { pointStart } from 'unist-util-position';
3
+ import { visit } from 'unist-util-visit';
4
+ /**
5
+ * Frontmatter whose opening `---` is missing.
6
+ *
7
+ * A document that starts
8
+ *
9
+ * ```
10
+ * weight: 13
11
+ * ---
12
+ * ```
13
+ *
14
+ * has no frontmatter at all. What it has is a setext heading: a line of text
15
+ * underlined by `---` is a level-two heading, so the page gets a heading called
16
+ * "weight: 13" and loses whatever the frontmatter was supposed to say.
17
+ *
18
+ * Nothing else notices. The file parses, every link resolves, the heading is a
19
+ * perfectly ordinary heading — `heading-increment` sees a rank drop from 2 to 1
20
+ * and is fine with it, `title-required` finds the `#` heading below and is
21
+ * satisfied. It took a *translation* to surface it, because comparing the two
22
+ * documents showed a heading the translation did not have. A single document
23
+ * cannot tell "weight: 13" from a heading someone meant to write; this rule can,
24
+ * because it only looks at the very first node and only at the keys doom's
25
+ * frontmatter actually uses.
26
+ *
27
+ * Measured on acp-docs before being turned on: 914 English documents, of which
28
+ * 88 legitimately have no frontmatter (generated api pages, index pages) — and
29
+ * exactly one of those 88 opens with something shaped like a frontmatter key.
30
+ * One true positive, no false ones. "Every document must have frontmatter"
31
+ * would have reported all 88.
32
+ */
33
+ /**
34
+ * The keys doom's frontmatter actually uses, counted across acp-docs rather
35
+ * than remembered: weight 797 · sourceSHA 194 · title 132 · i18n 125 ·
36
+ * queries 73 · description 21 · category 5 · author 4.
37
+ *
38
+ * Deliberately a list and not `\w+:` — a heading really can begin "Note:" or
39
+ * "Step 1:", and reporting those would be a rule nobody keeps.
40
+ */
41
+ const FRONTMATTER_KEYS = [
42
+ 'author',
43
+ 'category',
44
+ 'description',
45
+ 'i18n',
46
+ 'queries',
47
+ 'sourceSHA',
48
+ 'title',
49
+ 'weight',
50
+ ];
51
+ const OPENS_WITH_FRONTMATTER_KEY = new RegExp(`^(?:${FRONTMATTER_KEYS.join('|')})\\s*:`);
52
+ export const noUnopenedFrontmatter = lintRule('doom-lint:no-unopened-frontmatter', (root, vfile) => {
53
+ if (root.children.length === 0) {
54
+ return;
55
+ }
56
+ const [first] = root.children;
57
+ // Frontmatter that opened properly is a `yaml` node, not a heading.
58
+ if (first.type !== 'heading') {
59
+ return;
60
+ }
61
+ let text = '';
62
+ visit(first, 'text', (node) => {
63
+ text += node.value;
64
+ });
65
+ const match = OPENS_WITH_FRONTMATTER_KEY.exec(text.trim());
66
+ if (!match) {
67
+ return;
68
+ }
69
+ vfile.message(`This document opens with a heading called \`${text.trim()}\`, which is frontmatter that never opened: the \`---\` above it is missing, so the line below it underlined it into a heading instead. Add the opening \`---\`.`, { ancestors: [first], place: pointStart(first) });
70
+ });
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const noUnparsedEmphasis: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,53 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { pointStart } from 'unist-util-position';
3
+ import { visitParents } from 'unist-util-visit-parents';
4
+ /**
5
+ * Emphasis delimiters that did not become emphasis.
6
+ *
7
+ * `**bold**` only works when the delimiters flank the text: `** bold **` does
8
+ * not, and neither does `**注意:**卸载`, because the closing run is preceded by
9
+ * punctuation and followed by a letter. Either way the page shows the asterisks
10
+ * to the reader, and nothing else notices — the document parses, every link
11
+ * resolves, every component is present.
12
+ *
13
+ * A `text` node holding `**` is exactly that situation: the delimiters reached
14
+ * the tree as literal characters instead of wrapping anything.
15
+ *
16
+ * Measured on the acp-docs corpus before being turned on: 2 of 922 English
17
+ * documents, 7 of 875 Chinese, 2 of 875 Russian — 11 in all, every one of them
18
+ * a real page with literal asterisks on it, and two of them the English source
19
+ * of the Russian pair. The Chinese cases are the common shape: a translation
20
+ * writes `**注意:**此标签`, which is bold in the source's spacing and is not in
21
+ * the translation's.
22
+ *
23
+ * `__`, which CommonMark treats the same way, is covered by the same rule and
24
+ * by its tests, but was not measured — it does not occur in this corpus at all.
25
+ *
26
+ * A document that means to show literal asterisks says so with
27
+ * `<!-- lint disable no-unparsed-emphasis -->`.
28
+ */
29
+ /**
30
+ * A `**` anywhere, or a `__` that is not inside a word.
31
+ *
32
+ * `__` gets the narrower test because `snake__case` in prose is not emphasis
33
+ * anyone attempted, while `**` in prose is not something anyone types by
34
+ * accident.
35
+ */
36
+ const UNPARSED_EMPHASIS = /\*\*|(?<![\p{L}\p{N}])__|__(?![\p{L}\p{N}])/u;
37
+ export const noUnparsedEmphasis = lintRule('doom-lint:no-unparsed-emphasis', (root, vfile) => {
38
+ visitParents(root, 'text', (node, parents) => {
39
+ const match = UNPARSED_EMPHASIS.exec(node.value);
40
+ if (!match) {
41
+ return;
42
+ }
43
+ const delimiter = match[0];
44
+ vfile.message(`\`${delimiter}\` is printed to the page here, not read as emphasis: \`${preview(node.value, match.index)}\`. ` +
45
+ `Emphasis delimiters must sit directly against the text they emphasise — \`**text**\`, not \`** text **\` and not \`**text:**more\`.`, { ancestors: [...parents, node], place: pointStart(node) });
46
+ });
47
+ });
48
+ /** A short window around the offending delimiter, for a person reading the log. */
49
+ const preview = (value, index) => {
50
+ const from = Math.max(0, index - 20);
51
+ const to = Math.min(value.length, index + 30);
52
+ return `${from > 0 ? '…' : ''}${value.slice(from, to)}${to < value.length ? '…' : ''}`;
53
+ };
@@ -0,0 +1,40 @@
1
+ import type { Root } from 'mdast';
2
+ import type { Node, Position } from 'unist';
3
+ /**
4
+ * Build-integrity face for the API components (DOOM-1).
5
+ *
6
+ * Every `<K8sAPI>` / `<K8sCrd>` / `<OpenAPIRef>` / `<OpenAPIPath>` /
7
+ * `<K8sPermissionTable>` whose reference cannot be resolved renders a blank page
8
+ * (or a table with vanished rows) with a green `doom build`. These components
9
+ * scatter `console.error` calls that are never surfaced. This rule resolves the
10
+ * same sources the runtime plugins load and reports an unresolved reference at
11
+ * lint time, before it ships silently.
12
+ */
13
+ export interface ApiSources {
14
+ crdNames: Set<string>;
15
+ schemaNames: Set<string>;
16
+ /**
17
+ * OpenAPI schema names that carry no `x-kubernetes-group-version-kind`
18
+ * extension. `<K8sAPI>` derives the endpoint paths' group/version/kind from
19
+ * that extension (or from a CRD); without either, the paths cannot be built
20
+ * from facts and the caller has to declare them via props.
21
+ */
22
+ schemaNamesWithoutGvk: Set<string>;
23
+ pathNames: Set<string>;
24
+ functionNames: Set<string>;
25
+ }
26
+ /**
27
+ * Reads a Kubernetes source that may be either a single resource or a
28
+ * `kind: List` wrapper.
29
+ *
30
+ * The permission plugin unwraps `items` when it builds the runtime module, so a
31
+ * check that reads `metadata.name` off the wrapper finds nothing at all and
32
+ * then reports every reference as unresolved.
33
+ */
34
+ export declare const unwrapK8sList: <T>(doc: unknown) => T[];
35
+ /**
36
+ * The rule's decision logic, separated from source loading so it can be
37
+ * exercised against hand-built {@link ApiSources} in tests.
38
+ */
39
+ export declare const checkApiRefs: (root: Root, sources: ApiSources, report: (message: string, place: Position | undefined, ancestors: Node[]) => void) => void;
40
+ export declare const noUnresolvedApiRef: import("unified-lint-rule").Plugin<Root, unknown>;