@alauda/doom 2.5.4 → 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 (92) 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 +22 -3
  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 +16 -0
  30. package/lib/plugins/global/components.js +16 -1
  31. package/lib/remark-lint/index.d.ts +20 -0
  32. package/lib/remark-lint/index.js +40 -0
  33. package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
  34. package/lib/remark-lint/no-unmatched-anchor.js +13 -0
  35. package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
  36. package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
  37. package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
  38. package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
  39. package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
  40. package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
  41. package/lib/remark-lint/rule-sets.d.ts +75 -0
  42. package/lib/remark-lint/rule-sets.js +120 -0
  43. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  44. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  45. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  46. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  47. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  48. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  49. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  50. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  51. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  52. package/lib/remark-lint/translation-parity/index.js +24 -0
  53. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  54. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  55. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  56. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  57. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +26 -0
  58. package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
  59. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  60. package/lib/remark-lint/translation-parity/shared.js +282 -0
  61. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  62. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  63. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  64. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  65. package/lib/remark-lint/translation-parity/url-residue.d.ts +2 -0
  66. package/lib/remark-lint/translation-parity/url-residue.js +46 -0
  67. package/lib/remarkrc.d.ts +1 -1
  68. package/lib/remarkrc.js +7 -34
  69. package/lib/runtime/api-paths.d.ts +20 -0
  70. package/lib/runtime/api-paths.js +29 -0
  71. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  72. package/lib/runtime/components/K8sAPI.js +49 -10
  73. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  74. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  75. package/lib/runtime/components/OpenAPIPath.js +19 -2
  76. package/lib/runtime/components/_HeadingTitle.js +24 -6
  77. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  78. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  79. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  80. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  81. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  82. package/lib/runtime/components/_translation-policy.js +32 -0
  83. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  84. package/lib/runtime/translation.d.ts +68 -0
  85. package/lib/runtime/translation.js +51 -0
  86. package/lib/runtime/utils.d.ts +24 -2
  87. package/lib/runtime/utils.js +87 -5
  88. package/lib/shared/constants.d.ts +9 -0
  89. package/lib/shared/constants.js +14 -0
  90. package/lib/types.d.ts +70 -0
  91. package/lib/utils/helpers.js +8 -2
  92. package/package.json +3 -1
@@ -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;
@@ -1,2 +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;
1
17
  export declare const getGlobalComponentFiles: () => string[];
2
18
  export declare const getGlobalComponentNames: () => string[];
@@ -2,7 +2,22 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { baseResolve } from "../../utils/index.js";
4
4
  const componentsDir = baseResolve('runtime/components');
5
- const isGlobalComponentFile = (file) => {
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) => {
6
21
  const basename = path.basename(file, path.extname(file));
7
22
  return (!basename.startsWith('_') &&
8
23
  !basename.endsWith('.d') &&
@@ -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>;
@@ -0,0 +1,194 @@
1
+ import path from 'node:path';
2
+ import { glob } from 'tinyglobby';
3
+ import { lintRule } from 'unified-lint-rule';
4
+ import { visitParents } from 'unist-util-visit-parents';
5
+ import { resolveStaticConfig } from "../utils/helpers.js";
6
+ import { getConfig } from "./utils.js";
7
+ const GVK_EXTENSION = 'x-kubernetes-group-version-kind';
8
+ const hasGvk = (schema) => !!schema && typeof schema === 'object' && GVK_EXTENSION in schema;
9
+ let sourcesPromise;
10
+ const loadYamlOrJson = async (base, patterns) => {
11
+ if (!patterns?.length) {
12
+ return [];
13
+ }
14
+ const files = await glob(patterns, { cwd: base });
15
+ const out = [];
16
+ for (const file of files) {
17
+ try {
18
+ out.push(await resolveStaticConfig(path.resolve(base, file)));
19
+ }
20
+ catch {
21
+ // A file that fails to parse is a source problem of its own; skip it here
22
+ // so a single bad file does not blind the whole check.
23
+ }
24
+ }
25
+ return out;
26
+ };
27
+ /**
28
+ * Reads a Kubernetes source that may be either a single resource or a
29
+ * `kind: List` wrapper.
30
+ *
31
+ * The permission plugin unwraps `items` when it builds the runtime module, so a
32
+ * check that reads `metadata.name` off the wrapper finds nothing at all and
33
+ * then reports every reference as unresolved.
34
+ */
35
+ export const unwrapK8sList = (doc) => {
36
+ if (!doc || typeof doc !== 'object') {
37
+ return [];
38
+ }
39
+ const { items } = doc;
40
+ return Array.isArray(items) ? items : [doc];
41
+ };
42
+ const loadSources = async () => {
43
+ const { config, configFilePath } = await getConfig();
44
+ const base = configFilePath ? path.dirname(configFilePath) : config.root;
45
+ const crdNames = new Set();
46
+ const schemaNames = new Set();
47
+ const schemaNamesWithGvk = new Set();
48
+ const pathNames = new Set();
49
+ const functionNames = new Set();
50
+ const crds = await loadYamlOrJson(base, config.api?.crds);
51
+ for (const crd of crds) {
52
+ if (crd?.metadata?.name) {
53
+ crdNames.add(crd.metadata.name);
54
+ }
55
+ }
56
+ const openapis = await loadYamlOrJson(base, config.api?.openapis);
57
+ for (const doc of openapis) {
58
+ if (!doc) {
59
+ continue;
60
+ }
61
+ const components = doc.components;
62
+ // swagger 2.0 sources carry schemas under `definitions`.
63
+ const definitions = doc.definitions;
64
+ for (const [key, schema] of [
65
+ ...Object.entries(components?.schemas ?? {}),
66
+ ...Object.entries(definitions ?? {}),
67
+ ]) {
68
+ schemaNames.add(key);
69
+ if (hasGvk(schema)) {
70
+ schemaNamesWithGvk.add(key);
71
+ }
72
+ }
73
+ for (const key of Object.keys(doc.paths ?? {})) {
74
+ pathNames.add(key);
75
+ }
76
+ }
77
+ const functionResourceDocs = await loadYamlOrJson(base, config.permission?.functionresources);
78
+ for (const doc of functionResourceDocs) {
79
+ for (const fr of unwrapK8sList(doc)) {
80
+ if (fr.metadata?.name) {
81
+ functionNames.add(fr.metadata.name);
82
+ }
83
+ }
84
+ }
85
+ // A name defined in several sources counts as resolvable as long as *one* of
86
+ // them carries the extension — the runtime stops at the first source that
87
+ // resolves, so flagging the others would be a false positive.
88
+ const schemaNamesWithoutGvk = new Set([...schemaNames].filter((name) => !schemaNamesWithGvk.has(name)));
89
+ return {
90
+ crdNames,
91
+ schemaNames,
92
+ schemaNamesWithoutGvk,
93
+ pathNames,
94
+ functionNames,
95
+ };
96
+ };
97
+ /** Collect static string values from a JSX attribute (string, `{'x'}` or `{['a','b']}`). */
98
+ const staticStrings = (attr) => {
99
+ if (!attr) {
100
+ return [];
101
+ }
102
+ if (typeof attr.value === 'string') {
103
+ return [attr.value];
104
+ }
105
+ const estree = attr.value?.data?.estree;
106
+ const expr = estree?.body[0];
107
+ if (!expr || expr.type !== 'ExpressionStatement') {
108
+ return [];
109
+ }
110
+ const node = expr.expression;
111
+ if (node.type === 'Literal' && typeof node.value === 'string') {
112
+ return [node.value];
113
+ }
114
+ if (node.type === 'ArrayExpression') {
115
+ return node.elements.flatMap((el) => el && el.type === 'Literal' && typeof el.value === 'string'
116
+ ? [el.value]
117
+ : []);
118
+ }
119
+ // Anything dynamic (a variable, a computed value) cannot be validated here.
120
+ return [];
121
+ };
122
+ const attrOf = (element, name) => element.attributes.find((attr) => attr.type === 'mdxJsxAttribute' && attr.name === name);
123
+ /**
124
+ * The rule's decision logic, separated from source loading so it can be
125
+ * exercised against hand-built {@link ApiSources} in tests.
126
+ */
127
+ export const checkApiRefs = (root, sources, report) => {
128
+ const { crdNames, schemaNames, schemaNamesWithoutGvk, pathNames, functionNames, } = sources;
129
+ visitParents(root, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (element, parents) => {
130
+ const reportAt = (message, attr) => {
131
+ report(message, (attr ?? element).position, [...parents, element]);
132
+ };
133
+ switch (element.name) {
134
+ case 'K8sAPI':
135
+ case 'K8sCrd': {
136
+ const attr = attrOf(element, 'name');
137
+ const name = staticStrings(attr)[0];
138
+ if (!name) {
139
+ break;
140
+ }
141
+ if (!crdNames.has(name) && !schemaNames.has(name)) {
142
+ reportAt(`\`<${element.name}>\` references \`name="${name}"\`, which resolves to neither a CRD (\`api.crds\`) nor an OpenAPI schema (\`api.openapis\`). The page would render blank.`, attr);
143
+ break;
144
+ }
145
+ // The endpoint paths need a group/version/kind. It comes from the
146
+ // schema's `x-kubernetes-group-version-kind` extension, else from a
147
+ // CRD of the same name, else it has to be declared by the caller —
148
+ // aggregation-layer OpenAPI documents routinely ship without the
149
+ // extension. Without any of the three the endpoints section is
150
+ // dropped at render time, which a green build would otherwise hide.
151
+ if (schemaNamesWithoutGvk.has(name) &&
152
+ !crdNames.has(name) &&
153
+ // A spread (`{...props}`) can carry the props unseen; do not guess.
154
+ !element.attributes.some((attribute) => attribute.type === 'mdxJsxExpressionAttribute') &&
155
+ !(attrOf(element, 'apiVersion') && attrOf(element, 'apiKind'))) {
156
+ reportAt(`\`<${element.name} name="${name}">\` resolves to an OpenAPI schema without the \`${GVK_EXTENSION}\` extension, and no CRD defines it, so its group/version/kind cannot be derived. Pass explicit \`apiVersion\` and \`apiKind\` props (plus \`apiGroup\` for non-core groups, and \`plural\` if the plural is irregular), or the API endpoints section is omitted.`, attr);
157
+ }
158
+ break;
159
+ }
160
+ case 'OpenAPIRef': {
161
+ const attr = attrOf(element, 'schema');
162
+ const name = staticStrings(attr)[0];
163
+ if (name && !schemaNames.has(name)) {
164
+ reportAt(`\`<OpenAPIRef>\` references \`schema="${name}"\`, which is not defined in any \`api.openapis\` source.`, attr);
165
+ }
166
+ break;
167
+ }
168
+ case 'OpenAPIPath': {
169
+ const attr = attrOf(element, 'path');
170
+ for (const p of staticStrings(attr)) {
171
+ if (!pathNames.has(p)) {
172
+ reportAt(`\`<OpenAPIPath>\` references \`path\` \`${p}\`, which is not defined in any \`api.openapis\` source.`, attr);
173
+ }
174
+ }
175
+ break;
176
+ }
177
+ case 'K8sPermissionTable': {
178
+ const attr = attrOf(element, 'functions');
179
+ for (const fn of staticStrings(attr)) {
180
+ if (!functionNames.has(fn)) {
181
+ reportAt(`\`<K8sPermissionTable>\` references function \`${fn}\`, which is not a known FunctionResource (\`permission.functionresources\`). Its row would silently vanish.`, attr);
182
+ }
183
+ }
184
+ break;
185
+ }
186
+ default:
187
+ break;
188
+ }
189
+ });
190
+ };
191
+ export const noUnresolvedApiRef = lintRule('doom-lint:no-unresolved-api-ref', async (root, vfile) => {
192
+ const sources = await (sourcesPromise ??= loadSources());
193
+ checkApiRefs(root, sources, (message, place, ancestors) => vfile.message(message, { ancestors, place }));
194
+ });